GNUnet  0.10.x
gnunet_mq_lib.h
Go to the documentation of this file.
1 /*
2  This file is part of GNUnet.
3  Copyright (C) 2012-2016 GNUnet e.V.
4 
5  GNUnet is free software: you can redistribute it and/or modify it
6  under the terms of the GNU Affero General Public License as published
7  by the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  GNUnet is distributed in the hope that it will be useful, but
11  WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  Affero General Public License for more details.
14 
15  You should have received a copy of the GNU Affero General Public License
16  along with this program. If not, see <http://www.gnu.org/licenses/>.
17 
18  SPDX-License-Identifier: AGPL3.0-or-later
19  */
20 
35 #ifndef GNUNET_MQ_LIB_H
36 #define GNUNET_MQ_LIB_H
37 
38 #include "gnunet_scheduler_lib.h"
39 
52 #define GNUNET_MQ_msg_extra(mvar, esize, type) \
53  GNUNET_MQ_msg_(((struct GNUNET_MessageHeader **)&(mvar)), \
54  (esize) + sizeof *(mvar), \
55  (type))
56 
67 #define GNUNET_MQ_msg(mvar, type) GNUNET_MQ_msg_extra(mvar, 0, type)
68 
69 
76 #define GNUNET_MQ_msg_header(type) \
77  GNUNET_MQ_msg_(NULL, sizeof(struct GNUNET_MessageHeader), type)
78 
79 
88 #define GNUNET_MQ_msg_header_extra(mh, esize, type) \
89  GNUNET_MQ_msg_(&mh, (esize) + sizeof(struct GNUNET_MessageHeader), type)
90 
91 
102 #define GNUNET_MQ_msg_nested_mh(mvar, type, mh) \
103  ({ \
104  struct GNUNET_MQ_Envelope *_ev; \
105  _ev = GNUNET_MQ_msg_nested_mh_((struct GNUNET_MessageHeader **)&(mvar), \
106  sizeof(*(mvar)), \
107  (type), \
108  (mh)); \
109  (void)(mvar)->header; /* type check */ \
110  _ev; \
111  })
112 
113 
122 #define GNUNET_MQ_extract_nested_mh(var) \
123  GNUNET_MQ_extract_nested_mh_((struct GNUNET_MessageHeader *)(var), \
124  sizeof(*(var)))
125 
126 
135 const struct GNUNET_MessageHeader *
137  uint16_t base_size);
138 
139 
143 struct GNUNET_MQ_Envelope;
144 
145 
152 const struct GNUNET_MessageHeader *
154 
155 
162 const struct GNUNET_MQ_Envelope *
164 
165 
175 struct GNUNET_MQ_Envelope *
177  uint16_t base_size,
178  uint16_t type,
179  const struct GNUNET_MessageHeader *nested_mh);
180 
181 
185 struct GNUNET_MQ_Handle;
186 
187 
198 
203 
208 
214 
220 };
221 
222 
232 
237 
242 
247 
252 
266 
276 
284 
292 
297 };
298 
299 
306 typedef void (*GNUNET_MQ_MessageCallback) (
307  void *cls,
308  const struct GNUNET_MessageHeader *msg);
309 
310 
320  void *cls,
321  const struct GNUNET_MessageHeader *msg);
322 
323 
332 typedef void (*GNUNET_MQ_SendImpl) (struct GNUNET_MQ_Handle *mq,
333  const struct GNUNET_MessageHeader *msg,
334  void *impl_state);
335 
336 
346 typedef void (*GNUNET_MQ_DestroyImpl) (struct GNUNET_MQ_Handle *mq,
347  void *impl_state);
348 
349 
356 typedef void (*GNUNET_MQ_CancelImpl) (struct GNUNET_MQ_Handle *mq,
357  void *impl_state);
358 
359 
369 typedef void (*GNUNET_MQ_ErrorHandler) (void *cls, enum GNUNET_MQ_Error error);
370 
371 
384 void
386  struct GNUNET_MQ_Envelope **env_tail,
387  struct GNUNET_MQ_Envelope *env);
388 
389 
402 void
404  struct GNUNET_MQ_Envelope **env_tail,
405  struct GNUNET_MQ_Envelope *env);
406 
407 
420 void
421 GNUNET_MQ_dll_remove(struct GNUNET_MQ_Envelope **env_head,
422  struct GNUNET_MQ_Envelope **env_tail,
423  struct GNUNET_MQ_Envelope *env);
424 
425 
438 
439 
454  GNUNET_MQ_MessageCallback agpl_handler,
455  void *agpl_cls);
456 
457 
464 unsigned int
466 
467 
480 
487 
491  void *cls;
492 
496  uint16_t type;
497 
504  uint16_t expected_size;
505 };
506 
507 
511 #define GNUNET_MQ_handler_end() \
512  { \
513  NULL, NULL, NULL, 0, 0 \
514  }
515 
516 
545 #define GNUNET_MQ_hd_fixed_size(name, code, str, ctx) \
546  ({ \
547  void (*_cb)(void *cls, const str *msg) = &handle_ ## name; \
548  ((struct GNUNET_MQ_MessageHandler){ NULL, \
549  (GNUNET_MQ_MessageCallback)_cb, \
550  (ctx), \
551  (code), \
552  sizeof(str) }); \
553  })
554 
555 
596 #define GNUNET_MQ_hd_var_size(name, code, str, ctx) \
597  __extension__({ \
598  int (*_mv)(void *cls, const str *msg) = &check_ ## name; \
599  void (*_cb)(void *cls, const str *msg) = &handle_ ## name; \
600  ((struct GNUNET_MQ_MessageHandler){ (GNUNET_MQ_MessageValidationCallback) \
601  _mv, \
602  (GNUNET_MQ_MessageCallback)_cb, \
603  (ctx), \
604  (code), \
605  sizeof(str) }); \
606  })
607 
608 
619 #define GNUNET_MQ_check_zero_termination(m) \
620  { \
621  const char *str = (const char *)&m[1]; \
622  const struct GNUNET_MessageHeader *hdr = \
623  (const struct GNUNET_MessageHeader *)m; \
624  uint16_t slen = ntohs(hdr->size) - sizeof(*m); \
625  if ((0 == slen) || (memchr(str, 0, slen) != &str[slen - 1])) \
626  { \
627  GNUNET_break(0); \
628  return GNUNET_NO; \
629  } \
630  }
631 
632 
645 #define GNUNET_MQ_check_boxed_message(m) \
646  { \
647  const struct GNUNET_MessageHeader *inbox = \
648  (const struct GNUNET_MessageHeader *)&m[1]; \
649  const struct GNUNET_MessageHeader *hdr = \
650  (const struct GNUNET_MessageHeader *)m; \
651  uint16_t slen = ntohs(hdr->size) - sizeof(*m); \
652  if ((slen < sizeof(struct GNUNET_MessageHeader)) || \
653  (slen != ntohs(inbox->size))) \
654  { \
655  GNUNET_break(0); \
656  return GNUNET_NO; \
657  } \
658  }
659 
660 
673 int
675  const struct GNUNET_MessageHeader *mh);
676 
677 
686 struct GNUNET_MQ_Envelope *
688  uint16_t size,
689  uint16_t type);
690 
691 
698 struct GNUNET_MQ_Envelope *
699 GNUNET_MQ_msg_copy(const struct GNUNET_MessageHeader *hdr);
700 
701 
709 void
711 
712 
720 struct GNUNET_MQ_Envelope *
722 
723 
731 struct GNUNET_MQ_Envelope *
733 
734 
741 struct GNUNET_MQ_Envelope *
743 
744 
753 void
756 
757 
766 
767 
779 
780 
788 struct GNUNET_MQ_Envelope *
790 
791 
798 void
801 
802 
809 unsigned int
811 
812 
820 void
821 GNUNET_MQ_send(struct GNUNET_MQ_Handle *mq, struct GNUNET_MQ_Envelope *ev);
822 
823 
831 void
833  const struct GNUNET_MQ_Envelope *ev);
834 
835 
843 void
845 
846 
853 uint32_t
854 GNUNET_MQ_assoc_add(struct GNUNET_MQ_Handle *mq, void *assoc_data);
855 
856 
864 void *
865 GNUNET_MQ_assoc_get(struct GNUNET_MQ_Handle *mq, uint32_t request_id);
866 
867 
875 void *
876 GNUNET_MQ_assoc_remove(struct GNUNET_MQ_Handle *mq, uint32_t request_id);
877 
878 
891 struct GNUNET_MQ_Handle *
894  GNUNET_MQ_CancelImpl cancel,
895  void *impl_state,
896  const struct GNUNET_MQ_MessageHandler *handlers,
898  void *cls);
899 
900 
908 void
910  void *handlers_cls);
911 
912 
922 void
925  void *cb_cls);
926 
927 
933 void
935 
936 
942 
943 
956  void *cb_cls);
957 
963 void
966 
967 
978 void
980  const struct GNUNET_MessageHeader *mh);
981 
982 
993 void
995  enum GNUNET_MQ_Error error);
996 
997 
1008 void
1010 
1011 
1022 void
1024 
1025 
1040 void *
1042 
1043 
1053 const struct GNUNET_MessageHeader *
1055 
1056 
1067 
1073 
1079 
1085 
1089 #define GNUNET_MQ_PREFERENCE_COUNT 4
1090 };
1091 
1092 
1101 const char *
1103 
1104 
1105 #endif
1106  /* end of group mq */
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 ...
Definition: mq.c:1171
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 e...
Definition: mq.c:1038
struct GNUNET_MQ_Envelope * GNUNET_MQ_get_last_envelope(struct GNUNET_MQ_Handle *mq)
Function to obtain the last envelope in the queue.
Definition: mq.c:984
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 ...
Definition: mq.c:1150
Handle we return for callbacks registered to be notified when GNUNET_MQ_destroy() is called on a queu...
Definition: mq.c:787
struct GNUNET_MQ_Envelope * GNUNET_MQ_msg_copy(const struct GNUNET_MessageHeader *hdr)
Create a new envelope by copying an existing message.
Definition: mq.c:651
static void error_handler(void *cls, enum GNUNET_MQ_Error error)
We encountered an error handling the MQ to the ATS service.
void * impl_state
Implementation-specific state.
Definition: mq.c:109
Urgent traffic (local peer, i.e.
struct GNUNET_MessageHeader * msg
Definition: 005.c:2
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.
Definition: mq.c:1106
const struct GNUNET_MessageHeader * GNUNET_MQ_env_get_msg(const struct GNUNET_MQ_Envelope *env)
Obtain message contained in envelope.
Definition: mq.c:1077
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.
Definition: mq.c:298
uint16_t expected_size
Expected size of messages of this type.
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.
Definition: mq.c:706
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 c...
GNUNET_MQ_Error
Error codes for the queue.
We received a message for which we have no matching handler.
static struct GNUNET_CADET_Handle * mh
Cadet handle.
Definition: gnunet-cadet.c:92
struct GNUNET_MQ_MessageHandler * GNUNET_MQ_copy_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Copy an array of handlers.
Definition: mq.c:1211
void GNUNET_MQ_env_set_options(struct GNUNET_MQ_Envelope *env, enum GNUNET_MQ_PriorityPreferences pp)
Set application-specific options for this envelope.
Definition: mq.c:1002
No preference was expressed.
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 h...
Definition: mq.c:227
GNUNET_MQ_PriorityPreferences
Per envelope preferences and priorities.
const struct GNUNET_MessageHeader * GNUNET_MQ_impl_current(struct GNUNET_MQ_Handle *mq)
Get the message that should currently be sent.
Definition: mq.c:600
const struct GNUNET_MQ_Envelope * GNUNET_MQ_env_next(const struct GNUNET_MQ_Envelope *env)
Return next envelope in queue.
Definition: mq.c:1090
void(* GNUNET_SCHEDULER_TaskCallback)(void *cls)
Signature of the main function of a task.
Flag to indicate that low latency is important.
enum GNUNET_MQ_PriorityPreferences GNUNET_MQ_env_get_options(struct GNUNET_MQ_Envelope *env)
Get performance preferences set for this envelope.
Definition: mq.c:1017
Best-effort traffic (i.e.
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.
Definition: mq.c:581
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 #gn...
Definition: mq.c:517
uint16_t type
Type of the message this handler covers, in host byte order.
Flag to indicate that high bandwidth is desired.
GNUNET_MQ_PreferenceKind
Enum defining all known preference categories.
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.
Definition: mq.c:550
void * cls
Closure for mv and cb.
static struct GNUNET_CADET_MessageHandler handlers[]
Handlers, for diverse services.
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...
Definition: mq.c:772
GNUNET_MQ_MessageValidationCallback mv
Callback to validate a message of the specified type.
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.
Definition: mq.c:673
unsigned int GNUNET_MQ_get_length(struct GNUNET_MQ_Handle *mq)
Obtain the current length of the message queue.
Definition: mq.c:333
FIXME: document!
The preferred transmission for this envelope focuses on maximizing bandwidth.
Failed to read message from the network.
void * GNUNET_MQ_impl_state(struct GNUNET_MQ_Handle *mq)
Get the implementation state associated with the message queue.
Definition: mq.c:623
void(* GNUNET_MQ_DestroyImpl)(struct GNUNET_MQ_Handle *mq, void *impl_state)
Signature of functions implementing the destruction of a message queue.
GNUNET_MQ_MessageCallback cb
Callback, called every time a new message of the specified type has been receied. ...
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 m...
Definition: mq.c:200
We received a message that was malformed and thus could not be passed to its handler.
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.
Definition: mq.c:1241
struct GNUNET_MQ_Envelope * GNUNET_MQ_msg_(struct GNUNET_MessageHeader **mhp, uint16_t size, uint16_t type)
Create a new envelope.
Definition: mq.c:630
Message handler for a specific message type.
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.
Definition: mq.c:1192
unsigned int GNUNET_MQ_count_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Count the handlers in a handler array.
Definition: mq.c:1271
void GNUNET_MQ_discard(struct GNUNET_MQ_Envelope *mqm)
Discard the message queue message, free all allocated resources.
Definition: mq.c:319
FIXME: document!
static unsigned int size
Size of the "table".
Definition: peer.c:66
Lowest priority, i.e.
struct GNUNET_MQ_Envelope * env
Definition: 005.c:1
void(* GNUNET_MQ_CancelImpl)(struct GNUNET_MQ_Handle *mq, void *impl_state)
Implementation function that cancels the currently sent message.
Bit mask to apply to extract the priority bits.
void(* GNUNET_MQ_MessageCallback)(void *cls, const struct GNUNET_MessageHeader *msg)
Called when a message has been received.
Handle to a message queue.
Definition: mq.c:84
void GNUNET_MQ_set_options(struct GNUNET_MQ_Handle *mq, enum GNUNET_MQ_PriorityPreferences pp)
Set application-specific options for this queue.
Definition: mq.c:1063
const char * GNUNET_MQ_preference_to_string(enum GNUNET_MQ_PreferenceKind type)
Convert an enum GNUNET_MQ_PreferenceType to a string.
Definition: mq.c:1292
int(* GNUNET_MQ_MessageValidationCallback)(void *cls, const struct GNUNET_MessageHeader *msg)
Called when a message needs to be validated.
void * GNUNET_MQ_assoc_remove(struct GNUNET_MQ_Handle *mq, uint32_t request_id)
Remove the association for a request_id.
Definition: mq.c:750
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. ...
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.
Definition: mq.c:430
The preferred transmission for this envelope foces on minimizing latency.
struct GNUNET_MQ_Handle * mq
Definition: 003.c:5
Flag to indicate that out-of-order delivery is OK.
void GNUNET_MQ_destroy_notify_cancel(struct GNUNET_MQ_DestroyNotificationHandle *dnh)
Cancel registration from GNUNET_MQ_destroy_notify().
Definition: mq.c:1127
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.
Definition: mq.c:878
Flag to indicate that CORKing is acceptable.
enum GNUNET_TESTBED_UnderlayLinkModelType type
the type of this model
Header for all communications.
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.
Definition: mq.c:971
void GNUNET_MQ_destroy(struct GNUNET_MQ_Handle *mq)
Destroy the message queue.
Definition: mq.c:821
void GNUNET_MQ_send(struct GNUNET_MQ_Handle *mq, struct GNUNET_MQ_Envelope *ev)
Send a message with the given message queue.
Definition: mq.c:351
Flag to indicate that unreliable delivery is acceptable.
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...
Definition: mq.c:392
static void destroy(void *cls)
Highest priority, control traffic (i.e.
struct GNUNET_MQ_Envelope * GNUNET_MQ_env_copy(struct GNUNET_MQ_Envelope *env)
Function to copy an envelope.
Definition: mq.c:412
void GNUNET_MQ_impl_send_continue(struct GNUNET_MQ_Handle *mq)
Call the send implementation for the next queued message, if any.
Definition: mq.c:484
void GNUNET_MQ_send_cancel(struct GNUNET_MQ_Envelope *ev)
Cancel sending the message.
Definition: mq.c:913
void * cb_cls
Closure for cb.
Definition: mq.c:811
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.
Definition: mq.c:734
The preferred transmission for this envelope foces on reliability.