Low-level APIs for message-passing system. More...

#include "lib/dispatch/msgtypes.h"

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)

Detailed Description

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.

Macro Definition Documentation

◆ dispatch_free

#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.

◆ dispatch_free_msg

#define dispatch_free_msg	(	d,
		msg
	)

Value:

  STMT_BEGIN {                                                  \
    msg_t **msg_tmp_ptr__ = &(msg);                             \
    dispatch_free_msg_((d), *msg_tmp_ptr__);                    \
    *msg_tmp_ptr__= NULL;                                       \
  } STMT_END

Definition at line 104 of file dispatch.h.

Typedef Documentation

◆ dispatch_alertfn_t

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.

◆ dispatch_t

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 1 of file dispatch.h.

Function Documentation

◆ dispatch_flush()

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().

◆ dispatch_fmt_msg_data()

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().

◆ dispatch_free_()

void dispatch_free_ ( dispatch_t * d )

Release all storage held by d.

Definition at line 55 of file dispatch_core.c.

◆ dispatch_free_msg_()

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.

◆ dispatch_send()

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.

◆ dispatch_send_msg_unchecked()

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.

◆ dispatch_set_alert_fn()

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.

Macros

Typedefs

Functions