general purpose request queue More...

#include "platform.h"
#include "gnunet_util_lib.h"

Include dependency graph for mq.c:

Data Structures
struct	GNUNET_MQ_Envelope

struct	GNUNET_MQ_Handle
	Handle to a message queue. More...

struct	GNUNET_MQ_DestroyNotificationHandle
	Handle we return for callbacks registered to be notified when GNUNET_MQ_destroy() is called on a queue. More...

Macros
#define	LOG(kind, ...) GNUNET_log_from (kind, "util-mq", __VA_ARGS__)

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

static enum GNUNET_GenericReturnValue	handle_message (const struct GNUNET_MQ_MessageHandler handlers, const struct GNUNET_MessageHeader mh, bool log_unhandled)
	Call the message handler registered for the type of mh in the given handlers list.

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.

enum GNUNET_GenericReturnValue	GNUNET_MQ_try_handle_message (const struct GNUNET_MQ_MessageHandler handlers, const struct GNUNET_MessageHeader mh)
	Same as GNUNET_MQ_handle_message(), except that a message for which no handler is registered is not logged.

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.

void	GNUNET_MQ_discard (struct GNUNET_MQ_Envelope *ev)
	Discard the message queue message, free all allocated resources.

unsigned int	GNUNET_MQ_get_length (struct GNUNET_MQ_Handle *mq)
	Obtain the current length of the message queue.

void	GNUNET_MQ_send (struct GNUNET_MQ_Handle mq, struct GNUNET_MQ_Envelope ev)
	Send a message with the given message queue.

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.

struct GNUNET_MQ_Envelope *	GNUNET_MQ_env_copy (struct GNUNET_MQ_Envelope *env)
	Function to copy an envelope.

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.

static void	impl_send_continue (void *cls)
	Task run to call the send implementation for the next queued message, if any.

void	GNUNET_MQ_impl_send_continue (struct GNUNET_MQ_Handle *mq)
	Call the send implementation for the next queued message, if any.

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.

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 *error_handler_cls)
	Create a message queue for the specified handlers.

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.

const struct GNUNET_MessageHeader *	GNUNET_MQ_impl_current (struct GNUNET_MQ_Handle *mq)
	Get the message that should currently be sent.

void *	GNUNET_MQ_impl_state (struct GNUNET_MQ_Handle *mq)
	Get the implementation state associated with the message queue.

struct GNUNET_MQ_Envelope *	GNUNET_MQ_msg_ (struct GNUNET_MessageHeader **mhp, uint16_t size, uint16_t type)
	Create a new envelope.

struct GNUNET_MQ_Envelope *	GNUNET_MQ_msg_copy (const struct GNUNET_MessageHeader *hdr)
	Create a new envelope by copying an existing message.

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.

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.

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.

void *	GNUNET_MQ_assoc_remove (struct GNUNET_MQ_Handle *mq, uint32_t request_id)
	Remove the association for a request_id.

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.

void	GNUNET_MQ_destroy (struct GNUNET_MQ_Handle *mq)
	Destroy the message queue.

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.

void	GNUNET_MQ_send_cancel (struct GNUNET_MQ_Envelope *ev)
	Cancel sending the message.

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.

struct GNUNET_MQ_Envelope *	GNUNET_MQ_get_last_envelope (struct GNUNET_MQ_Handle *mq)
	Function to obtain the last envelope in the queue.

void	GNUNET_MQ_env_set_options (struct GNUNET_MQ_Envelope *env, enum GNUNET_MQ_PriorityPreferences pp)
	Set application-specific options for this envelope.

enum GNUNET_MQ_PriorityPreferences	GNUNET_MQ_env_get_options (struct GNUNET_MQ_Envelope *env)
	Get performance preferences set for this envelope.

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.

void	GNUNET_MQ_set_options (struct GNUNET_MQ_Handle *mq, enum GNUNET_MQ_PriorityPreferences pp)
	Set application-specific options for this queue.

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

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

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.

void	GNUNET_MQ_destroy_notify_cancel (struct GNUNET_MQ_DestroyNotificationHandle *dnh)
	Cancel registration from GNUNET_MQ_destroy_notify().

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.

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.

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.

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

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.

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

const char *	GNUNET_MQ_preference_to_string (enum GNUNET_MQ_PreferenceKind type)
	Convert an `enum GNUNET_MQ_PreferenceType` to a string.

Detailed Description

general purpose request queue

Author: Florian Dold

Definition in file mq.c.

Macro Definition Documentation

◆ LOG

#define LOG	(	kind,
		...
	)	GNUNET_log_from (kind, "util-mq", __VA_ARGS__)

Definition at line 30 of file mq.c.

Function Documentation

◆ handle_message()

static enum GNUNET_GenericReturnValue handle_message	(	const struct GNUNET_MQ_MessageHandler *	handlers,
		const struct GNUNET_MessageHeader *	mh,
		bool	log_unhandled
	)

static

Call the message handler registered for the type of mh in the given handlers list.

Parameters

handlers	a set of handlers, may be NULL
mh	message to dispatch
log_unhandled	log at GNUNET_ERROR_TYPE_INFO if no handler matched

Returns: GNUNET_OK on success, GNUNET_NO if no handler matched, GNUNET_SYSERR if message was rejected by check function

Definition at line 215 of file mq.c.

{
  bool handled = false;
  uint16_t msize = ntohs (mh->size);
  uint16_t mtype = ntohs (mh->type);
 
  LOG (GNUNET_ERROR_TYPE_DEBUG,
       "Received message of type %u and size %u\n",
       mtype,
       msize);
  if (NULL == handlers)
    goto done;
  for (const struct GNUNET_MQ_MessageHandler *handler = handlers;
       NULL != handler->cb;
       handler++)
  {
    if (handler->type == mtype)
    {
      handled = true;
      if ( (handler->expected_size > msize) ||
           ( (handler->expected_size != msize) &&
             (NULL == handler->mv) ) )
      {
        /* Too small, or not an exact size and
           no 'mv' handler to check rest */
        LOG (GNUNET_ERROR_TYPE_ERROR,
             "Received malformed message of type %u\n",
             (unsigned int) handler->type);
        return GNUNET_SYSERR;
      }
      if ( (NULL == handler->mv) ||
           (GNUNET_OK ==
            handler->mv (handler->cls,
                         mh)) )
      {
        /* message well-formed, pass to handler */
        handler->cb (handler->cls, mh);
      }
      else
      {
        /* Message rejected by check routine */
        LOG (GNUNET_ERROR_TYPE_ERROR,
             "Received malformed message of type %u\n",
             (unsigned int) handler->type);
        return GNUNET_SYSERR;
      }
      break;
    }
  }
done:
  if (! handled)
  {
    if (log_unhandled)
      LOG (GNUNET_ERROR_TYPE_INFO,
           "No handler for message of type %u and size %u\n",
           mtype,
           msize);
    return GNUNET_NO;
  }
  return GNUNET_OK;
}

References GNUNET_MQ_MessageHandler::cb, GNUNET_ERROR_TYPE_DEBUG, GNUNET_ERROR_TYPE_ERROR, GNUNET_ERROR_TYPE_INFO, GNUNET_NO, GNUNET_OK, GNUNET_SYSERR, handlers, LOG, and mh.

Referenced by GNUNET_MQ_handle_message(), and GNUNET_MQ_try_handle_message().

Here is the caller graph for this function:

◆ impl_send_continue()

static void impl_send_continue ( void * cls )

static

Task run to call the send implementation for the next queued message, if any.

Only useful for implementing message queues, results in undefined behavior if not used carefully.

Parameters

cls	message queue to send the next message with

Definition at line 441 of file mq.c.

{
  struct GNUNET_MQ_Handle *mq = cls;
  GNUNET_assert (NULL != mq->send_task);
 
  mq->send_task = NULL;
  /* call is only valid if we're actually currently sending
   * a message */
  if (NULL == mq->envelope_head)
    return;
  mq->current_envelope = mq->envelope_head;
  GNUNET_CONTAINER_DLL_remove (mq->envelope_head,
                               mq->envelope_tail,
                               mq->current_envelope);
 
  LOG (GNUNET_ERROR_TYPE_DEBUG,
       "sending message of type %u and size %u from queue (MQ: %p)\n",
       ntohs (mq->current_envelope->mh->type),
       ntohs (mq->current_envelope->mh->size),
       mq);
 
  mq->send_impl (mq,
                 mq->current_envelope->mh,
                 mq->impl_state);
}

References GNUNET_MQ_Handle::current_envelope, GNUNET_MQ_Handle::envelope_head, GNUNET_MQ_Handle::envelope_tail, GNUNET_assert, GNUNET_CONTAINER_DLL_remove, GNUNET_ERROR_TYPE_DEBUG, GNUNET_MQ_Handle::impl_state, LOG, GNUNET_MQ_Envelope::mh, mq, GNUNET_MQ_Handle::send_impl, GNUNET_MQ_Handle::send_task, GNUNET_MessageHeader::size, and GNUNET_MessageHeader::type.

Referenced by GNUNET_MQ_impl_send_continue().