aboutsummaryrefslogtreecommitdiff
path: root/src/messenger/testing_messenger_barrier.h
blob: 3062a393ad323e490a782390d2e08becbe9258a3 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
/*
   This file is part of GNUnet.
   Copyright (C) 2021 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
 */
/**
 * @file messenger/testing_messenger_barrier.h
 * @author Tobias Frisch
 * @brief Pseudo-barriers for simple event handling
 */

#ifndef GNUNET_TESTING_MESSENGER_BARRIER_H_
#define GNUNET_TESTING_MESSENGER_BARRIER_H_

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

/**
 * Handle for pseudo-barrier
 */
struct GNUNET_BarrierHandle;


/**
 * Functions of this type are to be given as callback argument to
 * GNUNET_init_barrier(). The callback will be called when status
 * information is available for the pseudo-barrier.
 *
 * @param cls the closure given to GNUNET_init_barrier()
 * @param barrier the pseudo-barrier handle
 * @param status status of the pseudo-barrier. The pseudo-barrier is removed
 *          once it has been crossed or an error occurs while processing it.
 *          Therefore it is invalid to call GNUNET_cancel_barrier() on a
 *          crossed or errored pseudo-barrier.
 */
typedef void
(*GNUNET_BarrierStatusCallback) (void *cls,
                                 struct GNUNET_BarrierHandle *barrier,
                                 int status);


/**
 * Initialise a pseudo-barrier and call the given callback when the required
 * amount of peers (requirement) reach the pseudo-barrier OR upon error.
 *
 * @param requirement the amount of peers that is required to reach the
 *   pseudo-barrier. Peers signal reaching a pseudo-barrier by calling
 *   GNUNET_wait_barrier().
 * @param cb the callback to call when the pseudo-barrier is reached or upon
 *   error. Can be NULL.
 * @param cls closure for the above callback
 * @return pseudo-barrier handle; NULL upon error
 */
struct GNUNET_BarrierHandle*
GNUNET_init_barrier (unsigned int requirement,
                     GNUNET_BarrierStatusCallback cb,
                     void *cb_cls);


/**
 * Cancel a pseudo-barrier.
 *
 * @param barrier the pseudo-barrier handle
 */
void
GNUNET_cancel_barrier (struct GNUNET_BarrierHandle *barrier);


/**
 * Handle for pseudo-barrier wait
 */
struct GNUNET_BarrierWaitHandle;


/**
 * Functions of this type are to be given as acallback argument to
 * GNUNET_wait_barrier(). The callback will be called when the pseudo-barrier
 * corresponding given in GNUNET_wait_barrier() is crossed or cancelled.
 *
 * @param cls closure pointer given to GNUNET_wait_barrier()
 * @param waiting the pseudo-barrier wait handle
 * @param status #GNUNET_SYSERR in case of error while waiting for the
 *   pseudo-barrier; #GNUNET_OK if the pseudo-barrier is crossed
 */
typedef void
(*GNUNET_BarrierWaitStatusCallback) (void *cls,
                                     struct GNUNET_BarrierWaitHandle *waiting,
                                     int status);


/**
 * Wait for a pseudo-barrier to be crossed. This function should be called for
 * the peers which have been started by the testbed.
 *
 * @param barrier the pseudo-barrier handle
 * @param cb the pseudo-barrier wait callback
 * @param cls the closure for the above callback
 * @return pseudo-barrier wait handle which can be used to cancel the waiting
 *   at anytime before the callback is called. NULL upon error.
 */
struct GNUNET_BarrierWaitHandle*
GNUNET_wait_barrier (struct GNUNET_BarrierHandle *barrier,
                     GNUNET_BarrierWaitStatusCallback cb,
                     void *cb_cls);


/**
 * Cancel a pseudo-barrier wait handle. Should not be called in or after the
 * callback given to GNUNET_wait_barrier() has been called.
 *
 * @param waiting the pseudo-barrier wait handle
 */
void
GNUNET_cancel_wait_barrier (struct GNUNET_BarrierWaitHandle *waiting);


#endif /* GNUNET_TESTING_MESSENGER_BARRIER_H_ */