|
Tor 0.4.9.0-alpha-dev
|
Low-level APIs for message-passing system. More...
#include "lib/dispatch/msgtypes.h"Go to the source code of this file.
Macros | |
| #define | dispatch_free(d) FREE_AND_NULL(dispatch_t, dispatch_free_, (d)) |
| #define | dispatch_free_msg(d, msg) |
Typedefs | |
| typedef struct dispatch_t | dispatch_t |
| typedef void(* | dispatch_alertfn_t) (struct dispatch_t *, channel_id_t, void *) |
Functions | |
| dispatch_t * | dispatch_new (const struct dispatch_cfg_t *cfg) |
| void | dispatch_free_ (dispatch_t *) |
| int | dispatch_send (dispatch_t *d, subsys_id_t sender, channel_id_t channel, message_id_t msg, msg_type_id_t type, msg_aux_data_t auxdata) |
| int | dispatch_send_msg (dispatch_t *d, msg_t *m) |
| int | dispatch_send_msg_unchecked (dispatch_t *d, msg_t *m) |
| int | dispatch_flush (dispatch_t *, channel_id_t chan, int max_msgs) |
| int | dispatch_set_alert_fn (dispatch_t *d, channel_id_t chan, dispatch_alertfn_t fn, void *userdata) |
| void | dispatch_free_msg_ (const dispatch_t *d, msg_t *msg) |
| char * | dispatch_fmt_msg_data (const dispatch_t *d, const msg_t *msg) |
Low-level APIs for message-passing system.
This module implements message dispatch based on a set of short integer identifiers. For a higher-level interface, see pubsub.h.
Each message is represented as a generic msg_t object, and is discriminated by its message_id_t. Messages are delivered by a dispatch_t object, which delivers each message to its recipients by a configured "channel".
A "channel" is a means of delivering messages. Every message_id_t must be associated with exactly one channel, identified by channel_id_t. When a channel receives messages, a callback is invoked to either process the messages immediately, or to cause them to be processed later.
Every message_id_t has zero or more associated receiver functions set up in the dispatch_t object. Once the dispatch_t object is created, receivers can be enabled or disabled [TODO], but not added or removed.
Every message_id_t has an associated datatype, identified by a msg_type_id_t. These datatypes can be associated with functions to (for example) free them, or format them for debugging.
To setup a dispatch_t object, first create a dispatch_cfg_t object, and configure messages with their types, channels, and receivers. Then, use dispatch_new() with that dispatch_cfg_t to create the dispatch_t object.
(We use a two-phase construction procedure here to enable better static reasoning about publish/subscribe relationships.)
Once you have a dispatch_t, you can queue messages on it with dispatch_send*(), and cause those messages to be delivered with dispatch_flush().
Definition in file dispatch.h.
| #define dispatch_free | ( | d | ) | FREE_AND_NULL(dispatch_t, dispatch_free_, (d)) |
Free a dispatcher. Tor does this at exit.
Definition at line 62 of file dispatch.h.
| #define dispatch_free_msg | ( | d, | |
| msg | |||
| ) |
Definition at line 104 of file dispatch.h.
| typedef void(* dispatch_alertfn_t) (struct dispatch_t *, channel_id_t, void *) |
Function callback type used to alert some other module when a channel's queue changes from empty to nonempty.
Ex 1: To cause messages to be processed immediately on-stack, this callback should invoke dispatch_flush() directly.
Ex 2: To cause messages to be processed very soon, from the event queue, this callback should schedule an event callback to run dispatch_flush().
Ex 3: To cause messages to be processed periodically, this function should do nothing, and a periodic event should invoke dispatch_flush().
Definition at line 98 of file dispatch.h.
| typedef struct dispatch_t dispatch_t |
A "dispatcher" is the highest-level object; it handles making sure that messages are received and delivered properly. Only the mainloop should handle this type directly.
Definition at line 53 of file dispatch.h.
| int dispatch_flush | ( | dispatch_t * | d, |
| channel_id_t | ch, | ||
| int | max_msgs | ||
| ) |
Run up to max_msgs callbacks for messages on the channel ch on the given dispatcher. Return 0 on success or recoverable failure, -1 on unrecoverable error.
Definition at line 241 of file dispatch_core.c.
Referenced by alertfn_immediate().
| char * dispatch_fmt_msg_data | ( | const dispatch_t * | d, |
| const msg_t * | msg | ||
| ) |
Format the auxiliary data held by msg.
Definition at line 43 of file dispatch_core.c.
Referenced by dispatch_send_msg_unchecked(), and dispatcher_run_msg_cbs().
| void dispatch_free_ | ( | dispatch_t * | d | ) |
Release all storage held by d.
Definition at line 55 of file dispatch_core.c.
| void dispatch_free_msg_ | ( | const dispatch_t * | d, |
| msg_t * | msg | ||
| ) |
Use d to drop all storage held for msg.
(We need the dispatcher so we know how to free the auxiliary data.)
Definition at line 30 of file dispatch_core.c.
| int dispatch_send | ( | dispatch_t * | d, |
| subsys_id_t | sender, | ||
| channel_id_t | channel, | ||
| message_id_t | msg, | ||
| msg_type_id_t | type, | ||
| msg_aux_data_t | auxdata | ||
| ) |
Send a message on the appropriate channel notifying that channel if necessary.
This function takes ownership of the auxiliary data; it can't be static or stack-allocated, and the caller is not allowed to use it afterwards.
This function does not check the various vields of the message object for consistency.
Definition at line 111 of file dispatch_core.c.
| int dispatch_send_msg | ( | dispatch_t * | d, |
| msg_t * | m | ||
| ) |
Definition at line 137 of file dispatch_core.c.
| int dispatch_send_msg_unchecked | ( | dispatch_t * | d, |
| msg_t * | m | ||
| ) |
Send a message on the appropriate queue, notifying that queue if necessary.
This function takes ownership of the message object and its auxiliary data; it can't be static or stack-allocated, and the caller isn't allowed to use it afterwards.
This function does not check the various fields of the message object for consistency, and can crash if they are out of range. Only functions that have already constructed the message in a safe way, or checked it for correctness themselves, should call this function.
Definition at line 175 of file dispatch_core.c.
| int dispatch_set_alert_fn | ( | dispatch_t * | d, |
| channel_id_t | chan, | ||
| dispatch_alertfn_t | fn, | ||
| void * | userdata | ||
| ) |
Tell the dispatcher to call fn with userdata whenever chan becomes nonempty. Return 0 on success, -1 on error.
Definition at line 88 of file dispatch_core.c.
1.9.4