gnunet_mq_lib.h

Go to the documentation of this file.

/*
     This file is part of GNUnet.
     Copyright (C) 2012-2016 GNUnet e.V.
 
     GNUnet is free software: you can redistribute it and/or modify it
     under the terms of the GNU Affero General Public License as published
     by the Free Software Foundation, either version 3 of the License,
     or (at your option) any later version.
 
     GNUnet is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Affero General Public License for more details.
 
     You should have received a copy of the GNU Affero General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
     SPDX-License-Identifier: AGPL3.0-or-later
 */
 
#include "gnunet_common.h"
#if ! defined (__GNUNET_UTIL_LIB_H_INSIDE__)
#error "Only <gnunet_util_lib.h> can be included directly."
#endif
 
 
#ifndef GNUNET_MQ_LIB_H
#define GNUNET_MQ_LIB_H
 
 
#include "gnunet_scheduler_lib.h"
 
#define GNUNET_MQ_msg_extra(mvar, esize, type)                \
        GNUNET_MQ_msg_ (((struct GNUNET_MessageHeader **) &(mvar)), \
                        (esize) + sizeof *(mvar),                   \
                        (type))
 
#define GNUNET_MQ_msg(mvar, type) GNUNET_MQ_msg_extra (mvar, 0, type)
 
 
#define GNUNET_MQ_msg_header(type) \
        GNUNET_MQ_msg_ (NULL, sizeof(struct GNUNET_MessageHeader), type)
 
 
#define GNUNET_MQ_msg_header_extra(mh, esize, type) \
        GNUNET_MQ_msg_ (&mh, (esize) + sizeof(struct GNUNET_MessageHeader), type \
                        )
 
 
#define GNUNET_MQ_msg_nested_mh(mvar, type, mh)                               \
        ({                                                                          \
    struct GNUNET_MQ_Envelope *_ev;                                           \
    _ev = GNUNET_MQ_msg_nested_mh_ ((struct GNUNET_MessageHeader **) &(mvar), \
                                    sizeof(*(mvar)),                         \
                                    (type),                                   \
                                    (mh));                                    \
    (void) (mvar)->header;  /* type check */                                   \
    _ev;                                                                      \
  })
 
 
#define GNUNET_MQ_extract_nested_mh(var)                               \
        GNUNET_MQ_extract_nested_mh_ ((struct GNUNET_MessageHeader *) (var), \
                                      sizeof(*(var)))
 
 
const struct GNUNET_MessageHeader *
GNUNET_MQ_extract_nested_mh_ (const struct GNUNET_MessageHeader *mh,
                              uint16_t base_size);
 
 
struct GNUNET_MQ_Envelope;
 
 
const struct GNUNET_MessageHeader *
GNUNET_MQ_env_get_msg (const struct GNUNET_MQ_Envelope *env);
 
 
const struct GNUNET_MQ_Envelope *
GNUNET_MQ_env_next (const struct GNUNET_MQ_Envelope *env);
 
 
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);
 
 
struct GNUNET_MQ_Handle;
 
 
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
};
 
 
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,
};
 
 
typedef void
(*GNUNET_MQ_MessageCallback) (
  void *cls,
  const struct GNUNET_MessageHeader *msg);
 
 
typedef enum GNUNET_GenericReturnValue
(*GNUNET_MQ_MessageValidationCallback) (
  void *cls,
  const struct GNUNET_MessageHeader *msg);
 
 
typedef void
(*GNUNET_MQ_SendImpl) (struct GNUNET_MQ_Handle *mq,
                       const struct GNUNET_MessageHeader *msg,
                       void *impl_state);
 
 
typedef void
(*GNUNET_MQ_DestroyImpl) (struct GNUNET_MQ_Handle *mq,
                          void *impl_state);
 
 
typedef void
(*GNUNET_MQ_CancelImpl) (struct GNUNET_MQ_Handle *mq,
                         void *impl_state);
 
 
typedef void
(*GNUNET_MQ_ErrorHandler) (void *cls,
                           enum GNUNET_MQ_Error error);
 
 
void
GNUNET_MQ_dll_insert_head (struct GNUNET_MQ_Envelope **env_head,
                           struct GNUNET_MQ_Envelope **env_tail,
                           struct GNUNET_MQ_Envelope *env);
 
 
void
GNUNET_MQ_dll_insert_tail (struct GNUNET_MQ_Envelope **env_head,
                           struct GNUNET_MQ_Envelope **env_tail,
                           struct GNUNET_MQ_Envelope *env);
 
 
void
GNUNET_MQ_dll_remove (struct GNUNET_MQ_Envelope **env_head,
                      struct GNUNET_MQ_Envelope **env_tail,
                      struct GNUNET_MQ_Envelope *env);
 
 
struct GNUNET_MQ_MessageHandler *
GNUNET_MQ_copy_handlers (const struct GNUNET_MQ_MessageHandler *handlers);
 
 
struct GNUNET_MQ_MessageHandler *
GNUNET_MQ_copy_handlers2 (const struct GNUNET_MQ_MessageHandler *handlers,
                          GNUNET_MQ_MessageCallback agpl_handler,
                          void *agpl_cls);
 
 
unsigned int
GNUNET_MQ_count_handlers (const struct GNUNET_MQ_MessageHandler *handlers);
 
 
struct GNUNET_MQ_MessageHandler
{
  GNUNET_MQ_MessageValidationCallback mv;
 
  GNUNET_MQ_MessageCallback cb;
 
  void *cls;
 
  uint16_t type;
 
  uint16_t expected_size;
};
 
 
#define GNUNET_MQ_handler_end() \
        {                             \
          NULL, NULL, NULL, 0, 0      \
        }
 
 
#define GNUNET_MQ_hd_fixed_size(name, code, str, ctx)                   \
        ({                                                                    \
    void (*_cb)(void *cls, const str *msg) = &handle_ ## name;           \
    ((struct GNUNET_MQ_MessageHandler){ NULL,                            \
                                        (GNUNET_MQ_MessageCallback) _cb, \
                                        (ctx),                           \
                                        (code),                          \
                                        sizeof(str) });                  \
  })
 
 
#define GNUNET_MQ_hd_var_size(name, code, str, ctx)                          \
        __extension__ ({                                                            \
    int (*_mv)(void *cls, const str *msg) = &check_ ## name;                  \
    void (*_cb)(void *cls, const str *msg) = &handle_ ## name;                \
    ((struct GNUNET_MQ_MessageHandler){ (GNUNET_MQ_MessageValidationCallback) \
                                        _mv,                                \
                                        (GNUNET_MQ_MessageCallback) _cb,      \
                                        (ctx),                                \
                                        (code),                               \
                                        sizeof(str) });                       \
  })
 
 
#define GNUNET_MQ_check_zero_termination(m)                       \
        {                                                               \
          const char *str = (const char *) &m[1];                       \
          const struct GNUNET_MessageHeader *hdr =                      \
            (const struct GNUNET_MessageHeader *) m;                    \
          uint16_t slen = ntohs (hdr->size) - sizeof(*m);              \
          if ((0 == slen) || (memchr (str, 0, slen) != &str[slen - 1])) \
          {                                                             \
            GNUNET_break (0);                                           \
            return GNUNET_NO;                                           \
          }                                                             \
        }
 
 
#define GNUNET_MQ_check_boxed_message(m)                 \
        {                                                      \
          const struct GNUNET_MessageHeader *inbox =           \
            (const struct GNUNET_MessageHeader *) &m[1];       \
          const struct GNUNET_MessageHeader *hdr =             \
            (const struct GNUNET_MessageHeader *) m;           \
          uint16_t slen = ntohs (hdr->size) - sizeof(*m);     \
          if ((slen < sizeof(struct GNUNET_MessageHeader)) || \
              (slen != ntohs (inbox->size)))                   \
          {                                                    \
            GNUNET_break (0);                                  \
            return GNUNET_NO;                                  \
          }                                                    \
        }
 
 
enum GNUNET_GenericReturnValue
GNUNET_MQ_handle_message (const struct GNUNET_MQ_MessageHandler *handlers,
                          const struct GNUNET_MessageHeader *mh);
 
 
enum GNUNET_GenericReturnValue
GNUNET_MQ_try_handle_message (const struct GNUNET_MQ_MessageHandler *handlers,
                              const struct GNUNET_MessageHeader *mh);
 
 
struct GNUNET_MQ_Envelope *
GNUNET_MQ_msg_ (struct GNUNET_MessageHeader **mhp,
                uint16_t size,
                uint16_t type);
 
 
struct GNUNET_MQ_Envelope *
GNUNET_MQ_msg_copy (const struct GNUNET_MessageHeader *hdr);
 
 
void
GNUNET_MQ_discard (struct GNUNET_MQ_Envelope *mqm);
 
 
struct GNUNET_MQ_Envelope *
GNUNET_MQ_get_current_envelope (struct GNUNET_MQ_Handle *mq);
 
 
struct GNUNET_MQ_Envelope *
GNUNET_MQ_env_copy (struct GNUNET_MQ_Envelope *env);
 
 
struct GNUNET_MQ_Envelope *
GNUNET_MQ_get_last_envelope (struct GNUNET_MQ_Handle *mq);
 
 
void
GNUNET_MQ_env_set_options (struct GNUNET_MQ_Envelope *env,
                           enum GNUNET_MQ_PriorityPreferences pp);
 
 
enum GNUNET_MQ_PriorityPreferences
GNUNET_MQ_env_get_options (struct GNUNET_MQ_Envelope *env);
 
 
enum GNUNET_MQ_PriorityPreferences
GNUNET_MQ_env_combine_options (enum GNUNET_MQ_PriorityPreferences p1,
                               enum GNUNET_MQ_PriorityPreferences p2);
 
 
struct GNUNET_MQ_Envelope *
GNUNET_MQ_unsent_head (struct GNUNET_MQ_Handle *mq);
 
 
void
GNUNET_MQ_set_options (struct GNUNET_MQ_Handle *mq,
                       enum GNUNET_MQ_PriorityPreferences pp);
 
 
unsigned int
GNUNET_MQ_get_length (struct GNUNET_MQ_Handle *mq);
 
 
void
GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq,
                struct GNUNET_MQ_Envelope *ev);
 
 
void
GNUNET_MQ_send_copy (struct GNUNET_MQ_Handle *mq,
                     const struct GNUNET_MQ_Envelope *ev);
 
 
void
GNUNET_MQ_send_cancel (struct GNUNET_MQ_Envelope *ev);
 
 
uint32_t
GNUNET_MQ_assoc_add (struct GNUNET_MQ_Handle *mq,
                     void *assoc_data);
 
 
void *
GNUNET_MQ_assoc_get (struct GNUNET_MQ_Handle *mq,
                     uint32_t request_id);
 
 
void *
GNUNET_MQ_assoc_remove (struct GNUNET_MQ_Handle *mq,
                        uint32_t request_id);
 
 
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);
 
 
void
GNUNET_MQ_set_handlers_closure (struct GNUNET_MQ_Handle *mq,
                                void *handlers_cls);
 
 
void
GNUNET_MQ_notify_sent (struct GNUNET_MQ_Envelope *ev,
                       GNUNET_SCHEDULER_TaskCallback cb,
                       void *cb_cls);
 
 
void
GNUNET_MQ_destroy (struct GNUNET_MQ_Handle *mq);
 
 
struct GNUNET_MQ_DestroyNotificationHandle;
 
 
struct GNUNET_MQ_DestroyNotificationHandle *
GNUNET_MQ_destroy_notify (struct GNUNET_MQ_Handle *mq,
                          GNUNET_SCHEDULER_TaskCallback cb,
                          void *cb_cls);
 
void
GNUNET_MQ_destroy_notify_cancel (
  struct GNUNET_MQ_DestroyNotificationHandle *dnh);
 
 
void
GNUNET_MQ_inject_message (struct GNUNET_MQ_Handle *mq,
                          const struct GNUNET_MessageHeader *mh);
 
 
void
GNUNET_MQ_inject_error (struct GNUNET_MQ_Handle *mq,
                        enum GNUNET_MQ_Error error);
 
 
void
GNUNET_MQ_impl_send_continue (struct GNUNET_MQ_Handle *mq);
 
 
void
GNUNET_MQ_impl_send_in_flight (struct GNUNET_MQ_Handle *mq);
 
 
void *
GNUNET_MQ_impl_state (struct GNUNET_MQ_Handle *mq);
 
 
const struct GNUNET_MessageHeader *
GNUNET_MQ_impl_current (struct GNUNET_MQ_Handle *mq);
 
 
enum GNUNET_MQ_PreferenceKind
{
  GNUNET_MQ_PREFERENCE_NONE = 0,
 
  GNUNET_MQ_PREFERENCE_BANDWIDTH = 1,
 
  GNUNET_MQ_PREFERENCE_LATENCY = 2,
 
  GNUNET_MQ_PREFERENCE_RELIABILITY = 3
 
#define GNUNET_MQ_PREFERENCE_COUNT 4
};
 
 
const char *
GNUNET_MQ_preference_to_string (enum GNUNET_MQ_PreferenceKind type);
 
 
#endif