GNUnet 0.21.0
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
21#include "gnunet_common.h"
22#if !defined (__GNUNET_UTIL_LIB_H_INSIDE__)
23#error "Only <gnunet_util_lib.h> can be included directly."
24#endif
25
26
45#ifndef GNUNET_MQ_LIB_H
46#define GNUNET_MQ_LIB_H
47
48
50
63#define GNUNET_MQ_msg_extra(mvar, esize, type) \
64 GNUNET_MQ_msg_ (((struct GNUNET_MessageHeader **) &(mvar)), \
65 (esize) + sizeof *(mvar), \
66 (type))
67
78#define GNUNET_MQ_msg(mvar, type) GNUNET_MQ_msg_extra (mvar, 0, type)
79
80
87#define GNUNET_MQ_msg_header(type) \
88 GNUNET_MQ_msg_ (NULL, sizeof(struct GNUNET_MessageHeader), type)
89
90
99#define GNUNET_MQ_msg_header_extra(mh, esize, type) \
100 GNUNET_MQ_msg_ (&mh, (esize) + sizeof(struct GNUNET_MessageHeader), type)
101
102
113#define GNUNET_MQ_msg_nested_mh(mvar, type, mh) \
114 ({ \
115 struct GNUNET_MQ_Envelope *_ev; \
116 _ev = GNUNET_MQ_msg_nested_mh_ ((struct GNUNET_MessageHeader **) &(mvar), \
117 sizeof(*(mvar)), \
118 (type), \
119 (mh)); \
120 (void) (mvar)->header; /* type check */ \
121 _ev; \
122 })
123
124
133#define GNUNET_MQ_extract_nested_mh(var) \
134 GNUNET_MQ_extract_nested_mh_ ((struct GNUNET_MessageHeader *) (var), \
135 sizeof(*(var)))
136
137
146const struct GNUNET_MessageHeader *
148 uint16_t base_size);
149
150
154struct GNUNET_MQ_Envelope;
155
156
163const struct GNUNET_MessageHeader *
165
166
173const struct GNUNET_MQ_Envelope *
175
176
186struct GNUNET_MQ_Envelope *
188 uint16_t base_size,
189 uint16_t type,
190 const struct GNUNET_MessageHeader *nested_mh);
191
192
196struct GNUNET_MQ_Handle;
197
198
203{
210
215
220
226
233
234
239{
245
250
255
260
265
279
289
297
305
310};
311
312
319typedef void
321 void *cls,
322 const struct GNUNET_MessageHeader *msg);
323
324
333typedef int
335 void *cls,
336 const struct GNUNET_MessageHeader *msg);
337
338
347typedef void
349 const struct GNUNET_MessageHeader *msg,
350 void *impl_state);
351
352
362typedef void
364 void *impl_state);
365
366
373typedef void
375 void *impl_state);
376
377
387typedef void
388(*GNUNET_MQ_ErrorHandler) (void *cls,
389 enum GNUNET_MQ_Error error);
390
391
404void
406 struct GNUNET_MQ_Envelope **env_tail,
407 struct GNUNET_MQ_Envelope *env);
408
409
422void
424 struct GNUNET_MQ_Envelope **env_tail,
425 struct GNUNET_MQ_Envelope *env);
426
427
440void
442 struct GNUNET_MQ_Envelope **env_tail,
443 struct GNUNET_MQ_Envelope *env);
444
445
458
459
474 GNUNET_MQ_MessageCallback agpl_handler,
475 void *agpl_cls);
476
477
484unsigned int
486
487
492{
501
508
512 void *cls;
513
517 uint16_t type;
518
526};
527
528
532#define GNUNET_MQ_handler_end() \
533 { \
534 NULL, NULL, NULL, 0, 0 \
535 }
536
537
566#define GNUNET_MQ_hd_fixed_size(name, code, str, ctx) \
567 ({ \
568 void (*_cb)(void *cls, const str *msg) = &handle_ ## name; \
569 ((struct GNUNET_MQ_MessageHandler){ NULL, \
570 (GNUNET_MQ_MessageCallback) _cb, \
571 (ctx), \
572 (code), \
573 sizeof(str) }); \
574 })
575
576
618#define GNUNET_MQ_hd_var_size(name, code, str, ctx) \
619 __extension__ ({ \
620 int (*_mv)(void *cls, const str *msg) = &check_ ## name; \
621 void (*_cb)(void *cls, const str *msg) = &handle_ ## name; \
622 ((struct GNUNET_MQ_MessageHandler){ (GNUNET_MQ_MessageValidationCallback) \
623 _mv, \
624 (GNUNET_MQ_MessageCallback) _cb, \
625 (ctx), \
626 (code), \
627 sizeof(str) }); \
628 })
629
630
641#define GNUNET_MQ_check_zero_termination(m) \
642 { \
643 const char *str = (const char *) &m[1]; \
644 const struct GNUNET_MessageHeader *hdr = \
645 (const struct GNUNET_MessageHeader *) m; \
646 uint16_t slen = ntohs (hdr->size) - sizeof(*m); \
647 if ((0 == slen) || (memchr (str, 0, slen) != &str[slen - 1])) \
648 { \
649 GNUNET_break (0); \
650 return GNUNET_NO; \
651 } \
652 }
653
654
667#define GNUNET_MQ_check_boxed_message(m) \
668 { \
669 const struct GNUNET_MessageHeader *inbox = \
670 (const struct GNUNET_MessageHeader *) &m[1]; \
671 const struct GNUNET_MessageHeader *hdr = \
672 (const struct GNUNET_MessageHeader *) m; \
673 uint16_t slen = ntohs (hdr->size) - sizeof(*m); \
674 if ((slen < sizeof(struct GNUNET_MessageHeader)) || \
675 (slen != ntohs (inbox->size))) \
676 { \
677 GNUNET_break (0); \
678 return GNUNET_NO; \
679 } \
680 }
681
682
697 const struct GNUNET_MessageHeader *mh);
698
699
708struct GNUNET_MQ_Envelope *
710 uint16_t size,
711 uint16_t type);
712
713
720struct GNUNET_MQ_Envelope *
721GNUNET_MQ_msg_copy (const struct GNUNET_MessageHeader *hdr);
722
723
731void
733
734
742struct GNUNET_MQ_Envelope *
744
745
753struct GNUNET_MQ_Envelope *
755
756
763struct GNUNET_MQ_Envelope *
765
766
775void
778
779
788
789
801
802
810struct GNUNET_MQ_Envelope *
812
813
820void
823
824
831unsigned int
833
834
842void
844 struct GNUNET_MQ_Envelope *ev);
845
846
854void
856 const struct GNUNET_MQ_Envelope *ev);
857
858
866void
868
869
876uint32_t
878 void *assoc_data);
879
880
888void *
890 uint32_t request_id);
891
892
900void *
902 uint32_t request_id);
903
904
917struct GNUNET_MQ_Handle *
921 void *impl_state,
924 void *cls);
925
926
934void
936 void *handlers_cls);
937
938
948void
951 void *cb_cls);
952
953
959void
961
962
968
969
982 void *cb_cls);
983
989void
992
993
1004void
1006 const struct GNUNET_MessageHeader *mh);
1007
1008
1019void
1021 enum GNUNET_MQ_Error error);
1022
1023
1034void
1036
1037
1048void
1050
1051
1066void *
1068
1069
1079const struct GNUNET_MessageHeader *
1081
1082
1089{
1094
1100
1106
1112
1116#define GNUNET_MQ_PREFERENCE_COUNT 4
1118
1119
1128const char *
1130
1131
1132#endif
1133 /* end of group mq */
1135 /* end of group addition */
struct GNUNET_MQ_MessageHandlers handlers[]
Definition: 003.c:1
struct GNUNET_MQ_Handle * mq
Definition: 003.c:5
struct GNUNET_MessageHeader * msg
Definition: 005.c:2
struct GNUNET_MQ_Envelope * env
Definition: 005.c:1
static void error_handler(void *cls, enum GNUNET_MQ_Error error)
Function called on connection trouble.
static struct GNUNET_CADET_Handle * mh
Cadet handle.
Definition: gnunet-cadet.c:92
static uint32_t type
Type string converted to DNS type value.
commonly used definitions; globals in this file are exempt from the rule that the module name ("commo...
API to schedule computations using continuation passing style.
uint16_t expected_size
Expected size of messages of this type.
GNUNET_MQ_MessageCallback cb
Callback, called every time a new message of the specified type has been received.
void * cls
Closure for mv and cb.
GNUNET_MQ_MessageValidationCallback mv
Callback to validate a message of the specified type.
GNUNET_GenericReturnValue
Named constants for return values.
uint16_t type
Type of the message this handler covers, in host byte order.
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:370
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:533
struct GNUNET_MQ_Envelope * GNUNET_MQ_env_copy(struct GNUNET_MQ_Envelope *env)
Function to copy an envelope.
Definition: mq.c:359
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:871
void GNUNET_MQ_send_cancel(struct GNUNET_MQ_Envelope *ev)
Cancel sending the message.
Definition: mq.c:768
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:946
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:830
unsigned int GNUNET_MQ_get_length(struct GNUNET_MQ_Handle *mq)
Obtain the current length of the message queue.
Definition: mq.c:293
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:740
GNUNET_MQ_Error
Error codes for the 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.
Definition: mq.c:344
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:269
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:465
int(* GNUNET_MQ_MessageValidationCallback)(void *cls, const struct GNUNET_MessageHeader *msg)
Called when a message needs to be validated.
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...
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:304
void(* GNUNET_MQ_DestroyImpl)(struct GNUNET_MQ_Handle *mq, void *impl_state)
Signature of functions implementing the destruction of a message queue.
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:924
void GNUNET_MQ_discard(struct GNUNET_MQ_Envelope *mqm)
Discard the message queue message, free all allocated resources.
Definition: mq.c:285
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:975
struct GNUNET_MQ_MessageHandler * GNUNET_MQ_copy_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Copy an array of handlers.
Definition: mq.c:957
GNUNET_MQ_PreferenceKind
Enum defining all known preference categories.
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:421
const char * GNUNET_MQ_preference_to_string(enum GNUNET_MQ_PreferenceKind type)
Convert an enum GNUNET_MQ_PreferenceType to a string.
Definition: mq.c:1013
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:604
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:893
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:852
const struct GNUNET_MQ_Envelope * GNUNET_MQ_env_next(const struct GNUNET_MQ_Envelope *env)
Return next envelope in queue.
Definition: mq.c:886
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:187
GNUNET_MQ_PriorityPreferences
Per envelope preferences and priorities.
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 h...
Definition: mq.c:205
void GNUNET_MQ_destroy_notify_cancel(struct GNUNET_MQ_DestroyNotificationHandle *dnh)
Cancel registration from GNUNET_MQ_destroy_notify().
Definition: mq.c:911
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:638
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:575
void(* GNUNET_MQ_MessageCallback)(void *cls, const struct GNUNET_MessageHeader *msg)
Called when a message has been received.
struct GNUNET_MQ_Envelope * GNUNET_MQ_msg_(struct GNUNET_MessageHeader **mhp, uint16_t size, uint16_t type)
Create a new envelope.
Definition: mq.c:516
const struct GNUNET_MessageHeader * GNUNET_MQ_env_get_msg(const struct GNUNET_MQ_Envelope *env)
Obtain message contained in envelope.
Definition: mq.c:879
enum GNUNET_MQ_PriorityPreferences GNUNET_MQ_env_get_options(struct GNUNET_MQ_Envelope *env)
Get performance preferences set for this envelope.
Definition: mq.c:839
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:444
void * GNUNET_MQ_assoc_remove(struct GNUNET_MQ_Handle *mq, uint32_t request_id)
Remove the association for a request_id.
Definition: mq.c:622
const struct GNUNET_MessageHeader * GNUNET_MQ_impl_current(struct GNUNET_MQ_Handle *mq)
Get the message that should currently be sent.
Definition: mq.c:500
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:489
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:820
void * GNUNET_MQ_impl_state(struct GNUNET_MQ_Handle *mq)
Get the implementation state associated with the message queue.
Definition: mq.c:509
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:548
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:935
void(* GNUNET_MQ_CancelImpl)(struct GNUNET_MQ_Handle *mq, void *impl_state)
Implementation function that cancels the currently sent message.
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.
unsigned int GNUNET_MQ_count_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Count the handlers in a handler array.
Definition: mq.c:1000
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:813
void GNUNET_MQ_destroy(struct GNUNET_MQ_Handle *mq)
Destroy the message queue.
Definition: mq.c:683
@ GNUNET_MQ_ERROR_READ
Failed to read message from the network.
@ GNUNET_MQ_ERROR_NO_MATCH
We received a message for which we have no matching handler.
@ GNUNET_MQ_ERROR_TIMEOUT
FIXME: document!
@ GNUNET_MQ_ERROR_MALFORMED
We received a message that was malformed and thus could not be passed to its handler.
@ GNUNET_MQ_ERROR_WRITE
FIXME: document!
@ GNUNET_MQ_PREFERENCE_RELIABILITY
The preferred transmission for this envelope foces on reliability.
@ GNUNET_MQ_PREFERENCE_NONE
No preference was expressed.
@ GNUNET_MQ_PREFERENCE_LATENCY
The preferred transmission for this envelope foces on minimizing latency.
@ GNUNET_MQ_PREFERENCE_BANDWIDTH
The preferred transmission for this envelope focuses on maximizing bandwidth.
@ GNUNET_MQ_PREF_OUT_OF_ORDER
Flag to indicate that out-of-order delivery is OK.
@ GNUNET_MQ_PRIO_URGENT
Urgent traffic (local peer, e.g.
@ GNUNET_MQ_PRIO_CRITICAL_CONTROL
Highest priority, control traffic (e.g.
@ GNUNET_MQ_PRIORITY_MASK
Bit mask to apply to extract the priority bits.
@ GNUNET_MQ_PRIO_BACKGROUND
Lowest priority, i.e.
@ GNUNET_MQ_PREF_CORK_ALLOWED
Flag to indicate that CORKing is acceptable.
@ GNUNET_MQ_PREF_UNRELIABLE
Flag to indicate that unreliable delivery is acceptable.
@ GNUNET_MQ_PREF_GOODPUT
Flag to indicate that high bandwidth is desired.
@ GNUNET_MQ_PREF_LOW_LATENCY
Flag to indicate that low latency is important.
@ GNUNET_MQ_PRIO_BEST_EFFORT
Best-effort traffic (e.g.
void(* GNUNET_SCHEDULER_TaskCallback)(void *cls)
Signature of the main function of a task.
static void destroy(void *cls)
Function to destroy a microphone.
Definition: microphone.c:153
static unsigned int size
Size of the "table".
Definition: peer.c:68
Handle we return for callbacks registered to be notified when GNUNET_MQ_destroy() is called on a queu...
Definition: mq.c:654
GNUNET_SCHEDULER_TaskCallback cb
Function to call.
Definition: mq.c:673
void * cb_cls
Closure for cb.
Definition: mq.c:678
Handle to a message queue.
Definition: mq.c:87
void * impl_state
Implementation-specific state.
Definition: mq.c:112
Message handler for a specific message type.
Header for all communications.