/**
* [[std]]
- * This allocator uses xmalloc(), xrealloc() and xfree(). The memory
+ * This allocator uses <<basics:xmalloc()>>, <<basics:xrealloc()>> and <<basics:xfree()>>. The memory
* it allocates is left unitialized.
**/
extern struct ucw_allocator ucw_allocator_std;
/**
* [[zeroing]]
- * This allocator uses xmalloc(), xrealloc() and xfree(). All memory
+ * This allocator uses <<basics:xmalloc()>>, <<basics:xrealloc()>> and <<basics:xfree()>>. All memory
* is zeroed upon allocation.
**/
extern struct ucw_allocator ucw_allocator_zeroed;
* previous and next pointers equal to NULL. Returns 0 or 1.
*
* Nodes initialized to all zeroes are unlinked, inserting a node anywhere in a list
- * makes it linked. Normal removal functions like clist_remove() do not mark nodes
- * as unlinked, you need to call clist_unlink() instead.
+ * makes it linked. Normal removal functions like @clist_remove() do not mark nodes
+ * as unlinked, you need to call @clist_unlink() instead.
**/
static inline int clist_is_linked(cnode *n)
{
* All configuration settings made within the context are rolled back
* (except when journalling is turned off). All memory allocated on behalf
* of the context is freed, which includes memory obtained by calls to
- * cf_malloc().
+ * @cf_malloc().
**/
void cf_delete_context(struct cf_context *cc);
/**
* Reload configuration from @file, replace the old one.
* If @file is NULL, reload all loaded configuration files and re-apply
- * bits of configuration passed to cf_set().
+ * bits of configuration passed to @cf_set().
* Returns a non-zero value upon error. In that case, all configuration
* settings are rolled back to the state before calling this function.
**/
void cf_open_group(void);
/**
- * Close a group opened by cf_open_group(). Returns a non-zero value upon error,
+ * Close a group opened by @cf_open_group(). Returns a non-zero value upon error,
* which usually means that a commit hook has failed.
**/
int cf_close_group(void);
#define DAEMON_ERR_LEN 256
-/** Parameters passed to daemon_control() **/
+/** Parameters passed to @daemon_control() **/
struct daemon_control_params {
const char *pid_file; // A path to PID file
const char *guard_file; // A path to guard file
is added. If it fails, the first one is replayed and the rollback
entry is removed.
-See <<cf_reload()>>.
+See @cf_reload().
[[custom_parser]]
Creating custom parsers
since there can be multiple instances of the daemon running simultaneously.
We therefore recommend the following daemon control protocol, which prevents all such
-race conditions. Its implementation is available in form of the daemon_control() library
+race conditions. Its implementation is available in form of the @daemon_control() library
function or the `ucw-daemon-control` stand-alone utility.
* There exist two files:
- `HASH_GIVE_ALLOC` -- you need to provide `void
\*HASH_PREFIX(alloc)(uns size` and `void HASH_PREFIX(free)(void \*)`
to allocate and deallocate the nodes. Default uses
- <<memory:xmalloc()>> and <<memory:xfree()>>, <<mempool:mempool
+ <<basics:xmalloc()>> and <<basics:xfree()>>, <<mempool:mempool
routines>> or <<eltpool:eltpool routines>>, depending on
<<use_pool,`HASH_USE_POOL`>>, <<auto_pool,`HASH_AUTO_POOL`>>,
<<use_eltpool,`HASH_USE_ELTPOOL`>> and <<auto_eltpool,`HASH_AUTO_ELTPOOL`>> switches.
- <<table_alloc:`HASH_GIVE_TABLE_ALLOC`>> -- you need to provide `void
\*HASH_PREFIX(table_alloc)(uns size` and `void HASH_PREFIX(table_free)(void \*)`
to allocate and deallocate the table itself. Default uses
- <<memory:xmalloc()>> and <<memory:xfree()>> or the functions
+ <<basics:xmalloc()>> and <<basics:xfree()>> or the functions
from `HASH_GIVE_ALLOC` depending on <<table_alloc:`HASH_TABLE_ALLOC`>> switch.
[[params]]
- `HASH_ZERO_FILL` -- initialize new nodes to all zeroes.
[[table-alloc]]
- `HASH_TABLE_ALLOC` -- allocate the table the same way as nodes. If
- not provided, <<mempory:xmalloc()>> is used.
+ not provided, <<basics:xmalloc()>> is used.
- `HASH_TABLE_GROWING` -- never decrease the size of allocated table of nodes.
[[table_dynamic]]
- `HASH_TABLE_DYNAMIC` -- By default, only one global hash table is
** *Incompatible:* As there may be more instances, we can no longer use
global variables to control the configuration system. In particular,
`cf_need_journal` and `cf_pool` variables have been replaced by
- functions <<conf:fun_cf_set_journalling,`cf_set_journalling()`>> and
- <<conf:fun_cf_get_pool,`cf_get_pool()`>>.
+ functions <<conf:cf_set_journalling()>> and <<conf:cf_get_pool()>>.
** *Incompatible:* Loading of configuration files has been decoupled from
the getopt wrapper, so you might need to include `conf.h` for functions
which were previously declared in `getopt.h`.
** New functions have been added:
- <<conf:fun_cf_open_group,`cf_open_group()`>>,
- <<conf:fun_cf_close_group,`cf_close_group()`>>, and
- <<conf:fun_cf_revert,`cf_revert()`>>.
+ <<conf:cf_open_group()>>, <<conf:cf_close_group()>>, and <<conf:cf_revert()>>.
** *Incompatible:* Dynamic configuration arrays have been re-implemented in
terms of our generic <<gary:,growing arrays>>. This makes them easier to
use and most of the interface has been preserved. The only exception is
However, the numerical values are equal, so old code should keep working.
** *Incompatible:* The main loop time (`main_now`) has been decoupled from wall clock time
and moved to a field in the `main_context` structure. It can be accessed either directly
- or via <<mainloop:fun_main_get_now,`main_get_now()`>>. The `main_now_seconds` variable has
+ or via <<mainloop:main_get_now()>>. The `main_now_seconds` variable has
been removed, `main_idle_time` has become a structure field.
** *Incompatible:* The interface for asynchronous reading and writing
(file_read() and friends) has been separated from the core of the main loop.
Use <<mainloop:struct_main_block_io,`struct main_block_io`>> and related functions instead.
-** *Incompatible:* file_close_all() is gone. You have to call <<mainloop:fun_main_teardown,`main_teardown()`>>
- or <<mainloop:fun_main_destroy,`main_destroy()`>> to clean up properly after fork().
+** *Incompatible:* file_close_all() is gone. You have to call <<mainloop:main_teardown()>>
+ or <<mainloop:main_destroy()>> to clean up properly after fork().
** Added support for <<mainloop:signal,synchronous delivery of signals>>.
-** Added relative timers: <<mainloop:fun_timer_add_rel,`timer_add_rel()`>>.
+** Added relative timers: <<mainloop:timer_add_rel()>>.
** Modification of events from a running event handler is always safe.
** Deleting an already deleted event is always safe.
-** For any event type, it is possible to ask whether it is active (added to the mainloop) or not: <<mainloop:fun_hook_is_active,`hook_is_active()`>> and friends.
+** For any event type, it is possible to ask whether it is active (added to the mainloop) or not: <<mainloop:hook_is_active()>> and friends.
** A new mainloop front-end for asynchronous <<mainloop:recordio,record-based I/O>> has been added.
* Added support for <<trans:,resource pools and transactions>>, which is a general
a much more convenient interface.
* The <<lists:,Circular linked lists>> can recognize unlinked nodes,
- see <<lists:fun_clist_unlink,`clist_unlink()`>>.
+ see <<lists:clist_unlink()>>.
* Added `strtonum.h` -- a module for precise parsing of numbers.
* When compiled by a recent enough GCC, `__thread` is used for thread-local variables,
which is more efficient than the POSIX per-thread storage.
** *Incompatible:* `ucwlib_context->thread_id` is no longer available directly,
- please use ucwlib_thread_id() instead.
+ please use <<thread:ucwlib_thread_id()>> instead.
* *Incompatible:* Several modules have been declared obsolete and removed:
** `sighandler` -- generic signal handling (it still exists internally)
* ^ ^ ^ ^
* buffer <= bstop (BE pos) <= bptr (FE pos) <= bufend
*
- * * This schema describes a fastbuf after its initialization or bflush().
+ * * This schema describes a fastbuf after its initialization or @bflush().
* * There is no cached data and we are ready for any read or write operation
* (well, only if the back-end supports it).
* * The interval `[bptr, bufend]` can be used by front-ends
* Raises `ucw.fb.open` if the file does not exist.
**/
struct fastbuf *bopen_file(const char *name, int mode, struct fb_params *params);
-struct fastbuf *bopen_file_try(const char *name, int mode, struct fb_params *params); /** Like bopen_file(), but returns NULL on failure. **/
+struct fastbuf *bopen_file_try(const char *name, int mode, struct fb_params *params); /** Like @bopen_file(), but returns NULL on failure. **/
/**
* Opens a temporary file.
/**
* Initialize a new `fbpool`. The structure is allocated by the caller,
- * so bclose() should not be called and no resource tying takes place.
+ * so @bclose() should not be called and no resource tying takes place.
**/
void fbpool_init(struct fbpool *fb); /** Initialize a new mempool fastbuf. **/
/**
/**
* Create a new growing array, initially containing @n elements,
* and let @ptr point to its first element. The memory used by the
- * array is allocated by xmalloc().
+ * array is allocated by <<basics:xmalloc()>>.
**/
#define GARY_INIT(ptr, n) (ptr) = gary_init(sizeof(*(ptr)), (n), &ucw_allocator_std)
/***
* === Message flags
*
- * The @flags parameter of msg() is divided to several groups of bits (from the LSB):
+ * The @flags parameter of <<basics:msg()>> is divided to several groups of bits (from the LSB):
* message severity level (`L_xxx`), destination stream, message type
* and control bits (e.g., `L_SIGHANDLER`).
***/
* In fact, it takes the fixed default stream and attaches @ls as its only
* substream. If there were any other substreams, they are removed.
*
- * Log streams created by log_file() or log_configured() are made default
+ * Log streams created by <<basics:log_file()>> or @log_configured() are made default
* by calling this function.
**/
void log_set_default_stream(struct log_stream *ls);
uns mp_open(struct mempool *pool, void *ptr);
/**
- * Inlined version of mp_open().
+ * Inlined version of @mp_open().
**/
static inline uns mp_open_fast(struct mempool *pool, void *ptr)
{
void *mp_realloc_zero(struct mempool *pool, void *ptr, uns size);
/**
- * Inlined version of mp_realloc().
+ * Inlined version of @mp_realloc().
**/
static inline void *mp_realloc_fast(struct mempool *pool, void *ptr, uns size)
{
#define OPT_HOOK_BEFORE_ARG 0x1 /** Call before option parsing **/
#define OPT_HOOK_BEFORE_VALUE 0x2 /** Call before value parsing **/
#define OPT_HOOK_AFTER_VALUE 0x4 /** Call after value parsing **/
-#define OPT_HOOK_FINAL 0x8 /** Call just before opt_parse() returns **/
+#define OPT_HOOK_FINAL 0x8 /** Call just before @opt_parse() returns **/
#define OPT_HOOK_INTERNAL 0x4000 // Used internally to ask for passing of struct opt_context
#endif
projects / libucw.git / commitdiff