GNUnet  0.11.x
Data Structures | Macros | Typedefs | Enumerations | Functions
gnunet_mq_lib.h File Reference
#include "gnunet_scheduler_lib.h"
Include dependency graph for gnunet_mq_lib.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

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

Macros

#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 `struct GNUNET_MQ_MessageHandler`

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
nameunique basename for the functions
codemessage type constant
strtype of the message (a struct)
ctxcontext 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_MessageHeaderGNUNET_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_MessageHeaderGNUNET_MQ_env_get_msg (const struct GNUNET_MQ_Envelope *env)
 Obtain message contained in envelope. More...
 
const struct GNUNET_MQ_EnvelopeGNUNET_MQ_env_next (const struct GNUNET_MQ_Envelope *env)
 Return next envelope in queue. More...
 
struct GNUNET_MQ_EnvelopeGNUNET_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_MessageHandlerGNUNET_MQ_copy_handlers (const struct GNUNET_MQ_MessageHandler *handlers)
 Copy an array of handlers. More...
 
struct GNUNET_MQ_MessageHandlerGNUNET_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 `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
nameunique basename for the functions
codemessage type constant
strtype of the message (a struct)
ctxcontext 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...
 
int 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_EnvelopeGNUNET_MQ_msg_ (struct GNUNET_MessageHeader **mhp, uint16_t size, uint16_t type)
 Create a new envelope. More...
 
struct GNUNET_MQ_EnvelopeGNUNET_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_EnvelopeGNUNET_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_EnvelopeGNUNET_MQ_env_copy (struct GNUNET_MQ_Envelope *env)
 Function to copy an envelope. More...
 
struct GNUNET_MQ_EnvelopeGNUNET_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_EnvelopeGNUNET_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_HandleGNUNET_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_DestroyNotificationHandleGNUNET_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_MessageHeaderGNUNET_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

Author
Florian Dold
Christian Grothoff

General-purpose message queue

Definition in file gnunet_mq_lib.h.

Macro Definition Documentation

◆ GNUNET_MQ_PREFERENCE_COUNT

#define GNUNET_MQ_PREFERENCE_COUNT   4