General-purpose message queue. More...

#include "gnunet_common.h"
#include "gnunet_scheduler_lib.h"

Include dependency graph for gnunet_mq_lib.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	GNUNET_MQ_MessageHandler
	Message handler for a specific message type. More...

Macros

#define GNUNET_MQ_LIB_H

#define GNUNET_MQ_msg_extra(mvar, esize, type)

Allocate an envelope, with extra space allocated after the space needed by the message struct. More...

#define GNUNET_MQ_msg(mvar, type) GNUNET_MQ_msg_extra (mvar, 0, type)

Allocate a GNUNET_MQ_Envelope. More...

#define GNUNET_MQ_msg_header(type) GNUNET_MQ_msg_ (NULL, sizeof(struct GNUNET_MessageHeader), type)

Allocate a GNUNET_MQ_Envelope, where the message only consists of a header. More...

#define GNUNET_MQ_msg_header_extra(mh, esize, type) GNUNET_MQ_msg_ (&mh, (esize) + sizeof(struct GNUNET_MessageHeader), type)

Allocate a GNUNET_MQ_Envelope, where the message only consists of a header and extra space. More...

#define GNUNET_MQ_msg_nested_mh(mvar, type, mh)

Allocate a GNUNET_MQ_Envelope, and append a payload message after the given message struct. More...

#define GNUNET_MQ_extract_nested_mh(var)

Return a pointer to the message at the end of the given message. More...

#define GNUNET_MQ_handler_end()

End-marker for the handlers array. More...

#define GNUNET_MQ_PREFERENCE_COUNT 4

will return a <tt>struct GNUNET_MQ_MessageHandler</tt>

Defines a static function name which takes as a single argument a message handler for fixed-sized messages of type code and with a message type argument of str.

Given such an argument, the function for the given message type.

The macro is to be used as follows: struct GNUNET_MessageTest { ... }; // must be fixed size static void handle_test_message (void *cls, const struct GNUNET_MessageTest *msg) { ... }

struct GNUNET_MQ_MessageHandler handlers[] = { GNUNET_MQ_hd_fixed_size(test_message, GNUNET_MESSAGE_TYPE_TEST, struct GNUNET_MessageTest, "context"), GNUNET_MQ_handler_end() };

Parameters


  
    name unique basename for the functions 
    code message type constant 
    str type of the message (a struct) 
    ctx context for the callbacks

#define GNUNET_MQ_hd_fixed_size(name, code, str, ctx)

Typedefs
typedef void(*	GNUNET_MQ_MessageCallback) (void cls, const struct GNUNET_MessageHeader msg)
	Called when a message has been received. More...

typedef int(*	GNUNET_MQ_MessageValidationCallback) (void cls, const struct GNUNET_MessageHeader msg)
	Called when a message needs to be validated. More...

typedef void(*	GNUNET_MQ_SendImpl) (struct GNUNET_MQ_Handle mq, const struct GNUNET_MessageHeader msg, void *impl_state)
	Signature of functions implementing the sending functionality of a message queue. More...

typedef void(*	GNUNET_MQ_DestroyImpl) (struct GNUNET_MQ_Handle mq, void impl_state)
	Signature of functions implementing the destruction of a message queue. More...

typedef void(*	GNUNET_MQ_CancelImpl) (struct GNUNET_MQ_Handle mq, void impl_state)
	Implementation function that cancels the currently sent message. More...

typedef void(*	GNUNET_MQ_ErrorHandler) (void *cls, enum GNUNET_MQ_Error error)
	Generic error handler, called with the appropriate error code and the same closure specified at the creation of the message queue. More...

Enumerations
enum	GNUNET_MQ_Error { GNUNET_MQ_ERROR_READ = 1 , GNUNET_MQ_ERROR_WRITE = 2 , GNUNET_MQ_ERROR_TIMEOUT = 4 , GNUNET_MQ_ERROR_MALFORMED = 8 , GNUNET_MQ_ERROR_NO_MATCH = 16 }
	Error codes for the queue. More...

enum	GNUNET_MQ_PriorityPreferences { GNUNET_MQ_PRIO_BACKGROUND = 0 , GNUNET_MQ_PRIO_BEST_EFFORT = 1 , GNUNET_MQ_PRIO_URGENT = 2 , GNUNET_MQ_PRIO_CRITICAL_CONTROL = 3 , GNUNET_MQ_PRIORITY_MASK = 3 , GNUNET_MQ_PREF_UNRELIABLE = 16 , GNUNET_MQ_PREF_LOW_LATENCY = 32 , GNUNET_MQ_PREF_CORK_ALLOWED = 64 , GNUNET_MQ_PREF_GOODPUT = 128 , GNUNET_MQ_PREF_OUT_OF_ORDER = 256 }
	Per envelope preferences and priorities. More...

Functions
const struct GNUNET_MessageHeader *	GNUNET_MQ_extract_nested_mh_ (const struct GNUNET_MessageHeader *mh, uint16_t base_size)
	Implementation of the #GNUNET_MQ_extract_nexted_mh macro. More...

const struct GNUNET_MessageHeader *	GNUNET_MQ_env_get_msg (const struct GNUNET_MQ_Envelope *env)
	Obtain message contained in envelope. More...

const struct GNUNET_MQ_Envelope *	GNUNET_MQ_env_next (const struct GNUNET_MQ_Envelope *env)
	Return next envelope in queue. More...

struct GNUNET_MQ_Envelope *	GNUNET_MQ_msg_nested_mh_ (struct GNUNET_MessageHeader *mhp, uint16_t base_size, uint16_t type, const struct GNUNET_MessageHeader nested_mh)
	Implementation of the GNUNET_MQ_msg_nested_mh macro. More...

void	GNUNET_MQ_dll_insert_head (struct GNUNET_MQ_Envelope env_head, struct GNUNET_MQ_Envelope env_tail, struct GNUNET_MQ_Envelope *env)
	Insert env into the envelope DLL starting at env_head Note that env must not be in any MQ while this function is used with DLLs defined outside of the MQ module. More...

void	GNUNET_MQ_dll_insert_tail (struct GNUNET_MQ_Envelope env_head, struct GNUNET_MQ_Envelope env_tail, struct GNUNET_MQ_Envelope *env)
	Insert env into the envelope DLL starting at env_head Note that env must not be in any MQ while this function is used with DLLs defined outside of the MQ module. More...

void	GNUNET_MQ_dll_remove (struct GNUNET_MQ_Envelope env_head, struct GNUNET_MQ_Envelope env_tail, struct GNUNET_MQ_Envelope *env)
	Remove env from the envelope DLL starting at env_head. More...

struct GNUNET_MQ_MessageHandler *	GNUNET_MQ_copy_handlers (const struct GNUNET_MQ_MessageHandler *handlers)
	Copy an array of handlers. More...

struct GNUNET_MQ_MessageHandler *	GNUNET_MQ_copy_handlers2 (const struct GNUNET_MQ_MessageHandler handlers, GNUNET_MQ_MessageCallback agpl_handler, void agpl_cls)
	Copy an array of handlers, appending AGPL handler. More...

unsigned int	GNUNET_MQ_count_handlers (const struct GNUNET_MQ_MessageHandler *handlers)
	Count the handlers in a handler array. More...

will return a <tt>struct

Defines a static function name which takes two arguments and a context-pointer for validating and handling variable-sized messages of type code and with a message type argument of str.

Given such arguments, the function GNUNET_MQ_MessageHandler for the given message type.

The macro is to be used as follows: struct GNUNET_MessageTest { ... }; // can be variable size static int check_test (void *cls, const struct GNUNET_MessageTest *msg) { const char *ctx = cls; GNUNET_assert (0 == strcmp ("context", ctx)); // ... } static void handle_test (void *cls, const struct GNUNET_MessageTest *msg) { const char *ctx = cls; GNUNET_assert (0 == strcmp ("context", ctx)); // ... }

struct GNUNET_MQ_MessageHandler handlers[] = { GNUNET_MQ_hd_var_size(test_message, GNUNET_MESSAGE_TYPE_TEST, struct GNUNET_MessageTest, "context"), GNUNET_MQ_handler_end() };

Parameters

name	unique basename for the functions
code	message type constant
str	type of the message (a struct)
ctx	context for the callbacks

#define GNUNET_MQ_hd_var_size(name, code, str, ctx)

#define GNUNET_MQ_check_zero_termination(m)

Insert code for a "check_" function that verifies that a given variable-length message received over the network is followed by a 0-terminated string. More...

#define GNUNET_MQ_check_boxed_message(m)

Insert code for a "check_" function that verifies that a given variable-length message received over the network is followed by another variable-length message that fits exactly with the given size. More...

enum GNUNET_MQ_PreferenceKind { GNUNET_MQ_PREFERENCE_NONE = 0 , GNUNET_MQ_PREFERENCE_BANDWIDTH = 1 , GNUNET_MQ_PREFERENCE_LATENCY = 2 , GNUNET_MQ_PREFERENCE_RELIABILITY }

Enum defining all known preference categories. More...

enum GNUNET_GenericReturnValue GNUNET_MQ_handle_message (const struct GNUNET_MQ_MessageHandler *handlers, const struct GNUNET_MessageHeader *mh)

Call the message message handler that was registered for the type of the given message in the given handlers list. More...

struct GNUNET_MQ_Envelope * GNUNET_MQ_msg_ (struct GNUNET_MessageHeader **mhp, uint16_t size, uint16_t type)

Create a new envelope. More...

struct GNUNET_MQ_Envelope * GNUNET_MQ_msg_copy (const struct GNUNET_MessageHeader *hdr)

Create a new envelope by copying an existing message. More...

void GNUNET_MQ_discard (struct GNUNET_MQ_Envelope *mqm)

Discard the message queue message, free all allocated resources. More...

struct GNUNET_MQ_Envelope * GNUNET_MQ_get_current_envelope (struct GNUNET_MQ_Handle *mq)

Function to obtain the current envelope from within GNUNET_MQ_SendImpl implementations. More...

struct GNUNET_MQ_Envelope * GNUNET_MQ_env_copy (struct GNUNET_MQ_Envelope *env)

Function to copy an envelope. More...

struct GNUNET_MQ_Envelope * GNUNET_MQ_get_last_envelope (struct GNUNET_MQ_Handle *mq)

Function to obtain the last envelope in the queue. More...

void GNUNET_MQ_env_set_options (struct GNUNET_MQ_Envelope *env, enum GNUNET_MQ_PriorityPreferences pp)

Set application-specific options for this envelope. More...

enum GNUNET_MQ_PriorityPreferences GNUNET_MQ_env_get_options (struct GNUNET_MQ_Envelope *env)

Get performance preferences set for this envelope. More...

enum GNUNET_MQ_PriorityPreferences GNUNET_MQ_env_combine_options (enum GNUNET_MQ_PriorityPreferences p1, enum GNUNET_MQ_PriorityPreferences p2)

Combine performance preferences set for different envelopes that are being combined into one larger envelope. More...

struct GNUNET_MQ_Envelope * GNUNET_MQ_unsent_head (struct GNUNET_MQ_Handle *mq)

Remove the first envelope that has not yet been sent from the message queue and return it. More...

void GNUNET_MQ_set_options (struct GNUNET_MQ_Handle *mq, enum GNUNET_MQ_PriorityPreferences pp)

Set application-specific options for this queue. More...

unsigned int GNUNET_MQ_get_length (struct GNUNET_MQ_Handle *mq)

Obtain the current length of the message queue. More...

void GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq, struct GNUNET_MQ_Envelope *ev)

Send a message with the given message queue. More...

void GNUNET_MQ_send_copy (struct GNUNET_MQ_Handle *mq, const struct GNUNET_MQ_Envelope *ev)

Send a copy of a message with the given message queue. More...

void GNUNET_MQ_send_cancel (struct GNUNET_MQ_Envelope *ev)

Cancel sending the message. More...

uint32_t GNUNET_MQ_assoc_add (struct GNUNET_MQ_Handle *mq, void *assoc_data)

Associate the assoc_data in mq with a unique request id. More...

void * GNUNET_MQ_assoc_get (struct GNUNET_MQ_Handle *mq, uint32_t request_id)

Get the data associated with a request_id in a queue. More...

void * GNUNET_MQ_assoc_remove (struct GNUNET_MQ_Handle *mq, uint32_t request_id)

Remove the association for a request_id. More...

struct GNUNET_MQ_Handle * GNUNET_MQ_queue_for_callbacks (GNUNET_MQ_SendImpl send, GNUNET_MQ_DestroyImpl destroy, GNUNET_MQ_CancelImpl cancel, void *impl_state, const struct GNUNET_MQ_MessageHandler *handlers, GNUNET_MQ_ErrorHandler error_handler, void *cls)

Create a message queue for the specified handlers. More...

void GNUNET_MQ_set_handlers_closure (struct GNUNET_MQ_Handle *mq, void *handlers_cls)

Change the closure argument in all of the handlers of the mq. More...

void GNUNET_MQ_notify_sent (struct GNUNET_MQ_Envelope *ev, GNUNET_SCHEDULER_TaskCallback cb, void *cb_cls)

Call a callback once the envelope has been sent, that is, sending it can not be canceled anymore. More...

void GNUNET_MQ_destroy (struct GNUNET_MQ_Handle *mq)

Destroy the message queue. More...

struct GNUNET_MQ_DestroyNotificationHandle * GNUNET_MQ_destroy_notify (struct GNUNET_MQ_Handle *mq, GNUNET_SCHEDULER_TaskCallback cb, void *cb_cls)

Register function to be called whenever mq is being destroyed. More...

void GNUNET_MQ_destroy_notify_cancel (struct GNUNET_MQ_DestroyNotificationHandle *dnh)

Cancel registration from GNUNET_MQ_destroy_notify(). More...

void GNUNET_MQ_inject_message (struct GNUNET_MQ_Handle *mq, const struct GNUNET_MessageHeader *mh)

Call the message message handler that was registered for the type of the given message in the given message queue. More...

void GNUNET_MQ_inject_error (struct GNUNET_MQ_Handle *mq, enum GNUNET_MQ_Error error)

Call the error handler of a message queue with the given error code. More...

void GNUNET_MQ_impl_send_continue (struct GNUNET_MQ_Handle *mq)

Call the send implementation for the next queued message, if any. More...

void GNUNET_MQ_impl_send_in_flight (struct GNUNET_MQ_Handle *mq)

Call the send notification for the current message, but do not try to send the next message until #gnunet_mq_impl_send_continue is called. More...

void * GNUNET_MQ_impl_state (struct GNUNET_MQ_Handle *mq)

Get the implementation state associated with the message queue. More...

const struct GNUNET_MessageHeader * GNUNET_MQ_impl_current (struct GNUNET_MQ_Handle *mq)

Get the message that should currently be sent. More...

const char * GNUNET_MQ_preference_to_string (enum GNUNET_MQ_PreferenceKind type)

Convert an enum GNUNET_MQ_PreferenceType to a string. More...

Detailed Description

General-purpose message queue.

Definition in file gnunet_mq_lib.h.

Macro Definition Documentation

◆ GNUNET_MQ_PREFERENCE_COUNT

#define GNUNET_MQ_PREFERENCE_COUNT 4

Data Structures

Macros

Typedefs

Enumerations

Functions

will return a <tt>struct

Detailed Description

Macro Definition Documentation

◆ GNUNET_MQ_PREFERENCE_COUNT