Signals API
[State Utility Library]

Typedefs
typedef sul_signal_group_t	sul_signal_group_t
typedef sul_signal_t	sul_signal_t
typedef sul_signal_hook_t	sul_signal_hook_t
typedef sul_error_t *(*	sul_sigfn_t )(sul_signal_t *signal, sul_tuple_t *tuple)
typedef sul_sigentries_t	sul_sigentries_t
Functions
	sul_signals_initialize (apr_pool_t *pool)
	sul_signals_create (const char *name, const char *f)
	sul_signals_destroy (const char *name)
	sul_signals_hook (const char *name, sul_sigfn_t fn)
	sul_signals_unhook (const char *name, sul_sigfn_t fn)
	sul_signals_get_signal (const char *name, sul_signal_t **signal)
	sul_signals_get_ring (const char *name, sul_sigentries_t **ring)
	sul_signals_valid (const char *name)
	sul_signals_emit (apr_pool_t *pool, const char *name,...)
	sul_signals_signal_name (sul_signal_t *signal)
	sul_signals_signal_type (sul_signal_t *signal)

---

Typedef Documentation

typedef struct sul_sigentries_t sul_sigentries_t

Collection of Signals.

typedef sul_error_t*(* sul_sigfn_t)(sul_signal_t *signal, sul_tuple_t *tuple)

Hook function prototype that is invoked for all Signals.

typedef struct sul_signal_group_t sul_signal_group_t

Function pointer and prototype for a signal function. It may be a good idea to someday customize this using macros so that when we do invoke the function pointer no warnings are produced.

typedef struct sul_signal_hook_t sul_signal_hook_t

Signal hook, an entry for a hook function that belongs to a Signal.

typedef struct sul_signal_t sul_signal_t

An individual Signal in a Signal Group.

---

Function Documentation

sul_signals_create (  const char *  name, const char *  f )

Creates a new Signal in the signal system. Parameters: name  Name of the signal to create. f  Parameter format of the Signal's function. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_destroy (  const char *  name  )

Removes an existing signal created with sul_signals_create from the system, this will render future calls to hook and unhook error prone. Parameters: name  Name of the signal to destroy. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_emit (  apr_pool_t *  pool, const char *  name, ...  )

Emits a signal, invoking all of the hooks that are registered for the signal. The pool is only used, for now, to allocate the tuple to store the arguments for the function, so the pool is only required for the lifetime of the CALL itself, afterwards it may be destroyed assuming that the hook functions don't keep their parameters around afterwards (string ones anyway) Parameters: pool  Pool to allocate memory overhead from. name  Name of the Signal to be emitted. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_get_ring (  const char *  name, sul_sigentries_t **  ring )

Gets the ring of signal entries for the signal with the specified name. Parameters: name  ring  Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_get_signal (  const char *  name, sul_signal_t **  signal )

Gets the signal with the specified name. Parameters: name  signal  Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_hook (  const char *  name, sul_sigfn_t  fn )

Hooks the given function into the signal with the specified name. If the signal can't be found then an error will be returned. Parameters: name  fn  Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_initialize (  apr_pool_t *  pool  )

Initializes the signals system, creating the internal tables and rings that the system uses to keep track of all the signals and their hooked functions. Parameters: pool  Pool to allocate any signal overhead from. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_signal_name (  sul_signal_t *  signal  )

Gets the name of a Signal. Parameters: signal  A signal. Returns: The signal's name.

sul_signals_signal_type (  sul_signal_t *  signal  )

Gets the type information for a Signal. Parameters: signal  A signal. Returns: The signal's type information.

sul_signals_unhook (  const char *  name, sul_sigfn_t  fn )

Unhooks the given function from the signal with the specified name. If the signal can't be found then an error will be returned. Parameters: name  fn  Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_signals_valid (  const char *  name  )

Returns true if a signal with the given name has been created. Parameters: name  Name of the signal to check for.

---