summaryrefslogtreecommitdiffstats
path: root/src/kiro-sb.h
blob: 32f1a488641f66da799dac15ae99ee4b81333765 (plain)
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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
/* Copyright (C) 2014-2015 Timo Dritschler <timo.dritschler@kit.edu>
   (Karlsruhe Institute of Technology)

   This library is free software; you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as published by the
   Free Software Foundation; either version 2.1 of the License, or (at your
   option) any later version.

   This library 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 Lesser General Public License for more
   details.

   You should have received a copy of the GNU Lesser General Public License along
   with this library; if not, write to the Free Software Foundation, Inc., 51
   Franklin St, Fifth Floor, Boston, MA 02110, USA
*/

/**
 * SECTION: kiro-sync-buffer
 * @Short_description: KIRO 'Synchronizing Buffer'
 * @Title: KiroSb
 *
 * KiroSb implements a 'Synchronizing Buffer' that automatically keeps the local
 * memory content up to date by mirroring the remote SyncBuffers memory content
 * automatically without any required user interaction
 */

#ifndef __KIRO_SB_H
#define __KIRO_SB_H

#include <stdint.h>
#include <glib-object.h>

G_BEGIN_DECLS

#define KIRO_TYPE_SB             (kiro_sb_get_type())
#define KIRO_SB(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), KIRO_TYPE_SB, KiroSb))
#define KIRO_IS_SB(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), KIRO_TYPE_SB))
#define KIRO_SB_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), KIRO_TYPE_SB, KiroSbClass))
#define KIRO_IS_SB_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), KIRO_TYPE_SB))
#define KIRO_SB_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), KIRO_TYPE_SB, KiroSbClass))


typedef struct _KiroSb           KiroSb;
typedef struct _KiroSbClass      KiroSbClass;
typedef struct _KiroSbPrivate    KiroSbPrivate;


struct _KiroSb {

    GObject parent;

};

struct _KiroSbClass {

    GObjectClass parent_class;

};


/* GObject and GType functions */
GType       kiro_sb_get_type           (void);

/**
 * kiro_sb_new:
 *
 *   Creates a new #KiroSb and returns a pointer to it.
 *
 * Returns: (transfer full): A pointer to a new #KiroSb
 * See also:
 *   kiro_sb_free
 */
KiroSb*    kiro_sb_new                (void);

/**
 * kiro_sb_free:
 * @sb: (transfer none): The #KiroSb that is to be freed
 *
 *   Clears all underlying memory and frees the object memory.
 *
 * Note:
 *   The internal memory is also freed when calling this function. If you want
 *   to continue using the raw @sb memory after you call this function, you need
 *   to memcpy() its content using the information optained from
 *   kiro_sb_get_element()
 * See also:
 *   kiro_sb_new, kiro_sb_get_element
 */
void        kiro_sb_free               (KiroSb *sb);

/**
 * kiro_sb_stop:
 * @sb: (transfer none): The #KiroSb to stop
 *
 *   The given #KiroSb is stopped and all internal memory is cleared. It is put
 *   back into its initial state and it can be used as if it was just created
 *
 * See also:
 *   kiro_sb_new, kiro_sb_serve, kiro_sb_clone
 */
void    kiro_sb_stop    (KiroSb *sb);


typedef gboolean KiroContinueFlag;
#define KIRO_CALLBACK_CONTINUE TRUE
#define KIRO_CALLBACK_REMOVE FALSE

/**
 * KiroSbSyncCallbackFunc:
 * @user_data: (transfer none): The #user_data which was provided during
 * registration of this callback
 *
 *   Defines the type of a callback function which will be invoked every time
 *   the #KiroSb syncs new data
 *
 * Returns: A #KiroContinueFlag deciding whether to keep this callback alive or not
 * Note:
 *   Returning %FALSE or %KIRO_CALLBACK_REMOVE will automatically remove the callback
 *   from the internal callback list. Return %TRUE or %KIRO_CALLBACK_CONTINUE if you
 *   want to keep the callback active
 * See also:
 *   kiro_sb_add_sync_callback, kiro_sb_remove_sync_callback, kiro_sb_clear_sync_callbacks
 */
typedef KiroContinueFlag (*KiroSbSyncCallbackFunc)   (void *user_data);

/**
 * kiro_sb_add_sync_callback:
 * @sb: (transfer none): The #KiroSb to register this callback to
 * @callback: (transfer none) (scope call): A function pointer to the callback function
 *
 *   Adds a callback to the passed #KiroSbSyncCallbackFunc to this #KiroSb which
 *   will be invoked every time the #KiroSb syncs new data.
 *
 * Returns: The internal id of the registerd callback
 * Note:
 *   The sync callbacks will only be invoked on a 'clonig' #KiroSb. All
 *   registered callbacks will be invoked in the order they were added to the
 *   #KiroSb.
 * See also:
 *   kiro_sb_remove_sync_callback, kiro_sb_clear_sync_callbacks
 */
gulong    kiro_sb_add_sync_callback (KiroSb *sb, KiroSbSyncCallbackFunc callback, void *user_data);

/**
 * kiro_sb_remove_sync_callback:
 * @sb: (transfer none): The #KiroSb to remove the callback from
 * @id: The id of the callback to be removed
 *
 *   Removes the callback with the given @id from the internal list. If the
 *   callback with the given @id was not found %FALSE is returned. If the
 *   callback with the given @id was found, it will be removed from the callback
 *   list and %TRUE is returned
 *
 * Returns: A #gboolean. %TRUE if the callback was found and removed. %FALSE
 *   otherwise
 * Note:
 *   Any currently active callback will still finish before it is removed from
 *   the list.
 * See also:
 *   kiro_sb_add_sync_callback, kiro_sb_clear_sync_callbacks
 */
gboolean    kiro_sb_remove_sync_callback (KiroSb *sb, gulong id);

/**
 * kiro_sb_clear_sync_callbacks:
 * @sb: (transfer none): The #KiroSb to perform this operation on
 *
 *   Removes all registerd callbacks from the internal list
 *
 * Note:
 *   Any currently active callbacks will still finish before they are removed
 *   from the list
 * See also:
 *   kiro_sb_add_sync_callback, kiro_sb_remove_sync_callback
 */
void    kiro_sb_clear_sync_callbacks (KiroSb *sb);

/**
 * kiro_sb_serve:
 * @sb: (transfer none): The #KiroSb to perform this operation on
 * @size: Size in bytes of the content that will be served
 * @addr: (transfer none): Optional address parameter to define where to
 * listen for new connections.
 * @port: (transfer none): Optional port to listen on for new connections
 *
 *   Allows other remote #KiroSbs to connect to this #KiroSb and clone its
 *   memory. The internal memory is initially empty. Use the kiro_sb_push or
 *   kiro_sb_push_dma functions to update the served data.
 *   If @addr is given the #KiroSb will try to bind to the InfiniBand device
 *   associated with the given address. If no address is given it will bind to
 *   the first device it can find. If @port is given, the #KiroSb will listen
 *   for new connections on this specific port. Otherwise, the default port
 *   '60010' will be used.
 *
 * Returns: A gboolean. TRUE = success. FALSE = fail.
 * Note:
 *   A #KiroSb that already 'serves' its content can no longer clone
 *   other remote #KiroSbs.
 * See also:
 *   kiro_sb_push, kiro_sb_push_dma
 */
gboolean    kiro_sb_serve           (KiroSb *sb, gulong size, const gchar *addr, const gchar *port);

/**
 * kiro_sb_clone:
 * @sb: (transfer none): The #KiroSb to perform this operation on
 * @address: (transfer none): The InfiniBand address of the remote #KiroSb
 * which should be cloned
 * @port: (transfer none): The InfiniBand port of the remote #KiroSb which
 * should be cloned
 *
 *   Connects to the remote #KiroSb given by @address and @port and
 *   continuousely clones its content into the local #KiroSb
 *
 * Returns: A gboolean. TRUE = connection successful. FALSE = connection failed.
 * Note:
 *   A #KiroSb that clones a remote #KiroSb can no longer start to 'serve' its
 *   content to other remote #KiroSbs
 * See also:
 *
 */
gboolean    kiro_sb_clone       (KiroSb *sb, const gchar *address, const gchar *port);

/**
 * kiro_sb_get_size:
 * @sb: (transfer none): The #KiroSb to perform this operation on
 *
 *   Returns the size in bytes of the content that is being served and/or cloned
 *   from.
 *
 * Returns: A gulong giving the size of the managed memory in bytes
 * Note:
 *   Since #KiroSb uses an internal triple buffer, the value gained from this
 *   function only gives the size of one element from that buffer. The size of
 *   the entire data structure will be different.
 * See also:
 *
 */
gulong      kiro_sb_get_size    (KiroSb *sb);

/**
 * kiro_sb_freeze:
 * @sb: (transfer none): The #KiroSb to perform this operation on
 *
 *   Stops the given #KiroSb from automatically syncing.
 *
 * See also:
 *   kiro_sb_thaw
 */
void      kiro_sb_freeze      (KiroSb *sb);

/**
 * kiro_sb_thaw:
 * @sb: (transfer none): The #KiroSb to perform this operation on
 *
 *   Enable the given #KiroSb automatic syncing.
 *
 * See also:
 *   kiro_sb_freeze
 */
void     kiro_sb_thaw         (KiroSb *sb);

/**
 * kiro_sb_get_data:
 * @sb: (transfer none) The #KiroSb to get the data from
 *
 *   Returns a void pointer to the most current incarnation of the stored data.
 *   Data might either change by pushing (in case of a 'serving' #KiroSb) or
 *   after (automatic or manual) syncing (in case of a 'cloning' #KiroSb).
 *
 * Returns: (transfer none) (type gulong):
 *   A void pointer the stored data
 * Note:
 *   The returned pointer to the element might become invalid at any time by
 *   automatic or manual sync. Under no circumstances might the returned pointer
 *   be freed by the user. If you want to ensure access to the pointed-to data
 *   after a sync, you should use memcpy().
 * See also:
 *   kiro_sb_freeze, kiro_sb_serve, kiro_sb_clone, kiro_sb_push,
 *   kiro_sb_push_dma, kiro_sb_get_data_blocking
 */
void*   kiro_sb_get_data     (KiroSb *sb);

/**
 * kiro_sb_get_data_blocking:
 * @sb: (transfer none) The #KiroSb to get the data from
 *
 *   Calling this function will do the same thing as kiro_sb_get_data, but it
 *   will internaly wait until new data has arived before returning it.
 *
 * Returns: (transfer none) (type gulong): A void pointer the stored data
 * Note:
 *   The returned pointer to the element might become invalid at any time by
 *   automatic or manual sync. Under no circumstances might the returned pointer
 *   be freed by the user. If you want to ensure access to the pointed-to data
 *   after a sync, you should use memcpy().
 * See also:
 *   kiro_sb_freeze, kiro_sb_serve, kiro_sb_clone, kiro_sb_push,
 *   kiro_sb_push_dma, kiro_sb_get_data
 */
void*   kiro_sb_get_data_blocking  (KiroSb *sb);

/**
 * kiro_sb_push:
 * @sb: (transfer none) The #KiroSb to get the data from
 * @data: (transfer none) (type gulong): void pointer to copy data from
 *
 *   Updates the internal memory by memcopy()-ing the given element into it.
 *   This operation is only valid for 'serving' #KiroSb. Calling this function
 *   on a 'cloning' #KiroSb will allways return %FALSE.
 *
 * Returns: %TRUE on success %FALSE in case of error
 * Note:
 *   The internal memcopy() will assume an element of the correct size (given
 *   with the initial call to kiro_sb_serve or returned by kiro_sb_get_size)
 * See also:
 *   kiro_sb_get_size, kiro_sb_serve
 */
gboolean kiro_sb_push       (KiroSb *sb, void *data);

/**
 * kiro_sb_push_dma:
 * @sb: (transfer none) The #KiroSb to get the data from
 *
 *   Returns a pointer where the new data should be stored.
 *   This operation is only valid for a 'serving' #KiroSb. Calling this
 *   function on a 'cloning' #KiroSb will allways return a %NULL pointer.
 *
 * Returns: (transfer none) (type gulong):
 *   A pointer to the memory where the new data should be stored
 * Note:
 *   It is the users responsibility to ensure no more data is written to the
 *   pointed memory then was specified with the initial call to kiro_sb_serve or
 *   returned by kiro_sb_get_size.  Under no circumstances might the returned
 *   pointer be freed by the user.
 * See also:
 *   kiro_sb_get_size, kiro_sb_serve
 */
void* kiro_sb_push_dma      (KiroSb *sb);

/**
 * kiro_sb_get_dma_pointer:
 * @sb: (transfer none) The #KiroSb to get the data from
 *
 *   Returns a pointer where the next element will be stored.
 *   This operation is only valid for a 'serving' #KiroSb. Calling this
 *   function on a 'cloning' #KiroSb will allways return a %NULL pointer.
 *
 * Returns: (transfer none) (type gulong):
 *   A pointer to the memory where the next element will be stored
 * Note:
 *   This function can be used to preemtively write data to the @sb without
 *   advancing the internal buffer (no remote sync will occur).  It is the users
 *   responsibility to ensure no more data is written to the pointed memory then
 *   was specified with the initial call to kiro_sb_serve or returned by
 *   kiro_sb_get_size.  Under no circumstances might the returned pointer be
 *   freed by the user.  Once the element has been written, you can use
 *   kiro_sb_push_dma() to advance the buffer, making the remote side aware of
 *   the new element.
 * See also:
 *   kiro_sb_get_size, kiro_sb_serve
 *
 * Since: 1.3
 */
void* kiro_sb_get_dma_pointer     (KiroSb *sb);

G_END_DECLS

#endif //__kiro_sb_H