forked from milk-org/ImageStreamIO
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ImageStreamIO.h
523 lines (445 loc) · 14 KB
/
ImageStreamIO.h
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
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
/**
* @file ImageStreamIO.h
* @brief Function prototypes for ImageStreamIO
*
*
*/
#ifndef _IMAGESTREAMIO_H
#define _IMAGESTREAMIO_H
#define CLOCK_ISIO CLOCK_TAI
#ifdef __cplusplus
extern "C"
{
#endif
#include "ImageStruct.h"
void __attribute__((constructor)) libinit_ImageStreamIO();
errno_t init_ImageStreamIO();
/** @brief Set the error reporting function to the default provided by the library.
*
* \returns IMAGESTREAMIO_SUCCESS on success
* \returns IMAGESTREAMIO_FAILURE on an error
*/
errno_t ImageStreamIO_set_default_printError();
/** @brief Set the error reporting function.
* The new function supplied by the pointer will be called whenever a library function reports an error.
* Pass `NULL` to turn off error reporting from within the library.
*
* \param new_printError is a pointer to the function to use for reporting errors. Can be NULL.
*
* \returns IMAGESTREAMIO_SUCCESS on success
* \returns IMAGESTREAMIO_FAILURE on an error
*/
errno_t ImageStreamIO_set_printError(errno_t (*new_printError)(const char *,
const char *, int, errno_t, char *));
/* =============================================================================================== */
/* =============================================================================================== */
/** @name ImageStreamIO - 0. Utilities */
/**@{ */
/* =============================================================================================== */
/* =============================================================================================== */
inline uint64_t ImageStreamIO_nbSlices(const IMAGE *image)
{
return (image->md->naxis == 3 ? image->md->size[2] : 1);
}
inline uint64_t ImageStreamIO_writeIndex(const IMAGE *image)
{
return (image->md->cnt1 + 1) % ImageStreamIO_nbSlices(image);
}
inline uint64_t ImageStreamIO_readLastWroteIndex(const IMAGE *image)
{
return (image->md->naxis == 3 ? image->md->cnt1 : 0);
}
/** @brief Get the raw pointer to the beginning of the slice slice_index.
*
*
* ## Purpose
*
* Return the raw pointer to the beginning of the slice slice_index
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[in]
* indec const int
* slice_index of the slice to read
*
* @param[out]
* buffer void**
* pointer to the beginning of the slice
*
* \return the error code
*/
errno_t ImageStreamIO_readBufferAt(
const IMAGE *image,
const unsigned int slice_index,
void **buffer
);
/** @brief Get the raw pointer where the producer should write.
*
*
* ## Purpose
*
* Return the raw pointer where the producer should write
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[out]
* buffer void**
* raw pointer where the producer should write
*
* \return the error code
*/
inline errno_t ImageStreamIO_writeBuffer(
const IMAGE *image, ///< [in] the name of the shared memory file
void **buffer ///< [out] raw pointer where the producer should write
)
{
const uint64_t write_index = ImageStreamIO_writeIndex(image);
return ImageStreamIO_readBufferAt(image, write_index, buffer);
}
/** @brief Get the raw pointer where the consumer will find the last frame wrote.
*
*
* ## Purpose
*
* Return the raw pointer where the consumer will find the last frame wrote
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[out]
* buffer void**
* raw pointer where the consumer will find the last frame wrote
*
* \return the error code
*/
inline errno_t ImageStreamIO_readLastWroteBuffer(
const IMAGE *image, ///< [in] the name of the shared memory file
void **buffer ///< [out] raw pointer where the consumer will find the last frame wrote
)
{
const int64_t read_index = ImageStreamIO_readLastWroteIndex(image);
return ImageStreamIO_readBufferAt(image, read_index, buffer);
}
/** @brief Get the standard stream filename.
*
* Fills in the \p file_name string with the standard shared memory image path, e.g.
* \code
* char file_name[64];
* ImageStreamIO_filename(file_name, 64, "image00");
* printf("%s\n", file_name);
* \endcode
* produces the output:
* \verbatim
* /milk/shm/image00.im.shm
8 \endverbatim
*
* \returns IMAGESTREAMIO_SUCCESS on success
* \returns IMAGESTREAMIO_FAILURE on error
*/
errno_t ImageStreamIO_filename(
char *file_name, ///< [out] the file name string to fill in
size_t ssz, ///< [in] the allocated size of file_name
const char *im_name ///< [in] the image name
);
/** @brief Get the size in bytes from the data type code.
*
* \returns the size in bytes of the data type if valid
* \returns -1 if atype is not valid
*/
int ImageStreamIO_typesize(uint8_t
atype /**< [in] the type code (see ImageStruct.h*/
);
const char* ImageStreamIO_typename(
uint8_t datatype
);
const char* ImageStreamIO_typename_short(
uint8_t datatype
);
const char* ImageStreamIO_typename_7(
uint8_t datatype
);
int ImageStreamIO_checktype(uint8_t datatype, int complex_allowed);
/** @brief Get the appropriate floating point type for arithmetic from any type
*
* \returns the atype of the matching float type
* \returns -1 if atype is not valid
*/
int ImageStreamIO_floattype(
uint8_t datatype
);
/** @brief Get the FITSIO BITPIX from the data type code.
*
* \returns the BITPIX if atype valid
* \returns -1 if atype is not valid
*/
int ImageStreamIO_FITSIObitpix(uint8_t
atype
);
int ImageStreamIO_FITSIOdatatype(uint8_t datatype);
///@}
/* =============================================================================================== */
/* =============================================================================================== */
/** @name ImageStreamIO - 1. READ / WRITE STREAM */
/**@{ */
/* =============================================================================================== */
/* =============================================================================================== */
/** @brief Create shared memory image stream (legacy API) */
errno_t ImageStreamIO_createIm(
IMAGE *image, ///< [out] IMAGE structure which will have its members allocated and initialized.
const char
*name, ///< [in] the name of the shared memory file will be data.tmpfsdir/<name>_im.shm
long naxis, ///< [in] number of axes in the image.
uint32_t *size, ///< [in] the size of the image along each axis. Must have naxis elements.
uint8_t atype, ///< [in] data type code
int shared, ///< [in] if true then a shared memory buffer is allocated. If false, only local storage is used.
int NBkw, ///< [in] the number of keywords to allocate.
int CBsize ///< [in] Circular Buffer size
);
/** @brief Create shared memory image stream */
errno_t ImageStreamIO_createIm_gpu(
IMAGE *image, ///< [out] IMAGE structure which will have its members allocated and initialized.
const char
*name, ///< [in] the name of the shared memory file will be data.tmpfsdir/<name>_im.shm
long naxis, ///< [in] number of axes in the image.
uint32_t *size, ///< [in] the size of the image along each axis. Must have naxis elements.
uint8_t atype, ///< [in] data type code
int8_t location, ///< [in] if -1 then a CPU memory buffer is allocated. If >=0, GPU memory buffer is allocated on devive `location`.
int shared, ///< [in] if true then a shared memory buffer is allocated. If false, only local storage is used.
int NBsem, ///< [in] the number of semaphores to allocate.
int NBkw, ///< [in] the number of keywords to allocate.
uint64_t imagetype,///< [in] type of the stream
uint32_t CBsize ///< [in] Number of circ buff frames if shared mem, 0 if unused
);
/** @brief Deallocate and remove an IMAGE structure.
*
* For a shared image:
* Closes all semaphores, deallcoates sem pointers,
* and removes associated files. Unmaps the shared memory
* segment, and finally removes the file. Sets the metadata and
* keyword pointers to NULL.
*
* For a non-shred image:
* Deallocates all arrays and sets pointers to NULL.
*
* \returns IMAGESTREAMIO_SUCCESS on success
* \returns IMAGESTREAMIO_FAILURE on an error (but currently no checks done)
*
*/
errno_t ImageStreamIO_destroyIm(
IMAGE *image /**< [in] The IMAGE structure to deallocate and remove from the system.*/
);
/** @brief Connect to an existing shared memory image stream
*
* Wrapper for \ref ImageStreamIO_read_sharedmem_image_toIMAGE
*/
errno_t ImageStreamIO_openIm(
IMAGE *image, ///< [out] IMAGE structure which will be attached to the existing IMAGE
const char
*name ///< [in] the name of the shared memory file will be data.tmpfsdir/<name>_im.shm
);
void *ImageStreamIO_get_image_d_ptr(IMAGE *image);
/** @brief Read / connect to existing shared memory image stream */
errno_t ImageStreamIO_read_sharedmem_image_toIMAGE(
const char
*name, ///< [in] the name of the shared memory file to access, as in data.tmpfsdir/<name>_im.shm
IMAGE *image ///< [out] the IMAGE structure to connect to the stream
);
/** @brief Close a shared memmory image stream.
*
* For use in clients, detaches and cleans up memory used by non-owner process.
*
* \returns IMAGESTREAMIO_SUCCESS on success
* \returns the appropriate error code otherwise if an error occurs
*
*/
errno_t ImageStreamIO_closeIm(IMAGE
*image /**< [in] A real-time image structure which contains the image data and meta-data.*/);
///@}
/* =============================================================================================== */
/* =============================================================================================== */
/** @name ImageStreamIO - 2. MANAGE SEMAPHORES */
/**@{ */
/* =============================================================================================== */
/* =============================================================================================== */
/** @brief Destroy shmim semaphores
*
* ## Purpose
*
* Destroy semaphore of a shmim
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*/
int ImageStreamIO_destroysem(
IMAGE *image ///< [in] the name of the shared memory file
);
/** @brief Create shmim semaphores
*
* ## Purpose
*
* Create semaphore of a shmim
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[in]
* NBsem number of semaphores to be created
*/
int ImageStreamIO_createsem(
IMAGE *image, ///< [in] the name of the shared memory file
long NBsem ///< [in] number of semaphores to be created
);
/** @brief Post all shmim semaphores
*
* ## Purpose
*
* Posts semaphore of a shmim
* if index < 0, post all semaphores
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[in]
* index semaphore index
* index of semaphore to be posted
* if index=-1, post all semaphores
*/
long ImageStreamIO_sempost(
IMAGE *image, ///< [in] the name of the shared memory file
long index ///< [in] semaphore index
);
/** @brief Post all shmim semaphores except one
*
* ## Purpose
*
* Posts all semaphores of a shmim except one
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[in]
* index semaphore index
* index of semaphore to be excluded
*/
long ImageStreamIO_sempost_excl(
IMAGE *image, ///< [in] the name of the shared memory file
long index ///< [in] semaphore index
);
/** @brief Post shmim semaphores at regular time interval
*
* ## Purpose
*
* Posts all semaphores of a shmim at regular time intervals
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[in]
* index semaphore index
* is =-1, post all semaphores
*
* @param[in]
* dtus time interval [us]
*
*/
long ImageStreamIO_sempost_loop(
IMAGE *image, ///< [in] the name of the shared memory file
long index, ///< [in] semaphore index
long dtus
);
/** @brief Get available semaphore index
*
*
*
*/
int ImageStreamIO_getsemwaitindex(
IMAGE *image, ///< [in] the name of the shared memory file
int semindexdefault
);
/** @brief Wait for semaphore
*
* ## Purpose
*
* Wait on a shmim semaphore
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[in]
* index semaphore index
*
*/
int ImageStreamIO_semwait(
IMAGE *image, ///< [in] the name of the shared memory file
int index ///< [in] semaphore index
);
int ImageStreamIO_semtrywait(
IMAGE *image, ///< [in] the name of the shared memory file
int index ///< [in] semaphore index
);
int ImageStreamIO_semtimedwait(
IMAGE *image, ///< [in] the name of the shared memory file
int index, ///< [in] semaphore index
const struct timespec *semwts
);
/** @brief Flush all semaphores of a shmim
*
* ## Purpose
*
* Flush shmim semaphore
*
* ## Arguments
*
* @param[in]
* image IMAGE*
* pointer to shmim
*
* @param[in]
* index semaphore index
* flush all semaphores if index<0
*
*/
long ImageStreamIO_semflush(
IMAGE *image, ///< [in] the name of the shared memory file
long index
);
long ImageStreamIO_semvalue(
IMAGE *image,
long index); // Warning returns in-band error if semID is bad.
long ImageStreamIO_UpdateIm(
IMAGE *image
);
///@}
#ifdef __cplusplus
} //extern "C"
#endif
#endif