Function prototypes for ImageStreamIO. More...

#include "ImageStruct.h"

Include dependency graph for ImageStreamIO.h:

This graph shows which files directly or indirectly include this file:

Functions
void	__attribute__ ((constructor)) libinit_ImageStreamIO()
	Initialize module. More...

errno_t	init_ImageStreamIO ()

errno_t	ImageStreamIO_set_default_printError ()
	Set the error reporting function to the default provided by the library. More...

errno_t	ImageStreamIO_set_printError (errno_t(new_printError)(const char , const char , int, errno_t, char ))
	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. More...

ImageStreamIO - 0. Utilities
uint64_t	ImageStreamIO_nbSlices (const IMAGE *image)

uint64_t	ImageStreamIO_writeIndex (const IMAGE *image)

uint64_t	ImageStreamIO_readLastWroteIndex (const IMAGE *image)

errno_t	ImageStreamIO_readBufferAt (const IMAGE image, const unsigned int slice_index, void *buffer)
	Get the raw pointer to the beginning of the slice slice_index. More...

errno_t	ImageStreamIO_writeBuffer (const IMAGE image, void *buffer)
	Get the raw pointer where the producer should write. More...

errno_t	ImageStreamIO_readLastWroteBuffer (const IMAGE image, void *buffer)
	Get the raw pointer where the consumer will find the last frame wrote. More...

errno_t	ImageStreamIO_filename (char file_name, size_t ssz, const char im_name)
	Get the standard stream filename. More...

int	ImageStreamIO_typesize (uint8_t atype)
	Get the size in bytes from the data type code. More...

int	ImageStreamIO_bitpix (uint8_t atype)
	Get the FITSIO BITPIX from the data type code. More...

ImageStreamIO - 1. READ / WRITE STREAM
errno_t	ImageStreamIO_createIm (IMAGE image, const char name, long naxis, uint32_t *size, uint8_t atype, int shared, int NBkw)
	Create shared memory image stream (legacy API) More...

errno_t	ImageStreamIO_createIm_gpu (IMAGE image, const char name, long naxis, uint32_t *size, uint8_t atype, int8_t location, int shared, int NBsem, int NBkw, uint64_t imagetype)
	Create shared memory image stream. More...

errno_t	ImageStreamIO_destroyIm (IMAGE *image)
	Deallocate and remove an IMAGE structure. More...

errno_t	ImageStreamIO_openIm (IMAGE image, const char name)
	Connect to an existing shared memory image stream. More...

void *	ImageStreamIO_get_image_d_ptr (IMAGE *image)

errno_t	ImageStreamIO_read_sharedmem_image_toIMAGE (const char name, IMAGE image)
	Read / connect to existing shared memory image stream. More...

errno_t	ImageStreamIO_closeIm (IMAGE *image)
	Close a shared memmory image stream. More...

ImageStreamIO - 2. MANAGE SEMAPHORES
int	ImageStreamIO_destroysem (IMAGE *image)
	Destroy shmim semaphores. More...

int	ImageStreamIO_createsem (IMAGE *image, long NBsem)
	Create shmim semaphores. More...

long	ImageStreamIO_sempost (IMAGE *image, long index)
	Post all shmim semaphores. More...

long	ImageStreamIO_sempost_excl (IMAGE *image, long index)
	Post all shmim semaphores except one. More...

long	ImageStreamIO_sempost_loop (IMAGE *image, long index, long dtus)
	Post shmim semaphores at regular time interval. More...

int	ImageStreamIO_getsemwaitindex (IMAGE *image, int semindexdefault)
	Get available semaphore index. More...

int	ImageStreamIO_semwait (IMAGE *image, int index)
	Wait for semaphore. More...

int	ImageStreamIO_semtrywait (IMAGE *image, int index)

int	ImageStreamIO_semtimedwait (IMAGE image, int index, const struct timespec semwts)

long	ImageStreamIO_semflush (IMAGE *image, long index)
	Flush all semaphores of a shmim. More...

Detailed Description

Function prototypes for ImageStreamIO.

Function Documentation

◆ attribute()

void __attribute__ ( (constructor) )

Initialize module.

◆ ImageStreamIO_bitpix()

int ImageStreamIO_bitpix ( uint8_t atype )

Get the FITSIO BITPIX from the data type code.

Returns: the BITPIX if atype valid; -1 if atype is not valid

Parameters

[in] atype the type code (see ImageStruct.h

◆ ImageStreamIO_closeIm()

errno_t ImageStreamIO_closeIm ( IMAGE * image )

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; the appropriate error code otherwise if an error occurs

Parameters

[in] image A real-time image structure which contains the image data and meta-data.

◆ ImageStreamIO_createIm()

errno_t ImageStreamIO_createIm	(	IMAGE *	image,
		const char *	name,
		long	naxis,
		uint32_t *	size,
		uint8_t	atype,
		int	shared,
		int	NBkw
	)

Create shared memory image stream (legacy API)

Parameters

[out]	image	IMAGE structure which will have its members allocated and initialized.
[in]	name	the name of the shared memory file will be data.tmpfsdir/<name>_im.shm
[in]	naxis	number of axes in the image.
[in]	size	the size of the image along each axis. Must have naxis elements.
[in]	atype	data type code
[in]	shared	if true then a shared memory buffer is allocated. If false, only local storage is used.
[in]	NBkw	the number of keywords to allocate.

◆ ImageStreamIO_createIm_gpu()

errno_t ImageStreamIO_createIm_gpu	(	IMAGE *	image,
		const char *	name,
		long	naxis,
		uint32_t *	size,
		uint8_t	atype,
		int8_t	location,
		int	shared,
		int	NBsem,
		int	NBkw,
		uint64_t	imagetype
	)

Create shared memory image stream.

Parameters

[out]	image	IMAGE structure which will have its members allocated and initialized.
[in]	name	the name of the shared memory file will be data.tmpfsdir/<name>_im.shm
[in]	naxis	number of axes in the image.
[in]	size	the size of the image along each axis. Must have naxis elements.
[in]	atype	data type code
[in]	location	if -1 then a CPU memory buffer is allocated. If >=0, GPU memory buffer is allocated on devive `location`.
[in]	shared	if true then a shared memory buffer is allocated. If false, only local storage is used.
[in]	NBsem	the number of semaphores to allocate.
[in]	NBkw	the number of keywords to allocate.
[in]	imagetype	type of the stream

◆ ImageStreamIO_createsem()

int ImageStreamIO_createsem	(	IMAGE *	image,
		long	NBsem
	)

Create shmim semaphores.

Purpose

Create semaphore of a shmim

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	NBsem	number of semaphores to be created

Parameters

[in]	image	the name of the shared memory file
[in]	NBsem	number of semaphores to be created

◆ ImageStreamIO_destroyIm()

errno_t ImageStreamIO_destroyIm ( IMAGE * image )

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; IMAGESTREAMIO_FAILURE on an error (but currently no checks done)

Parameters

[in] image The IMAGE structure to deallocate and remove from the system.

◆ ImageStreamIO_destroysem()

int ImageStreamIO_destroysem ( IMAGE * image )

Destroy shmim semaphores.

Purpose

Destroy semaphore of a shmim

Arguments

Parameters

[in] image IMAGE* pointer to shmim

Parameters

[in] image the name of the shared memory file

◆ ImageStreamIO_filename()

errno_t ImageStreamIO_filename	(	char *	file_name,
		size_t	ssz,
		const char *	im_name
	)

Get the standard stream filename.

Fills in the file_name string with the standard shared memory image path, e.g.

char file_name[64];
ImageStreamIO_filename(file_name, 64, "image00");
printf("%s\n", file_name);

produces the output:

*    /milk/shm/image00.im.shm
8

Returns: IMAGESTREAMIO_SUCCESS on success; IMAGESTREAMIO_FAILURE on error

Parameters

[out]	file_name	the file name string to fill in
[in]	ssz	the allocated size of file_name
[in]	im_name	the image name

◆ ImageStreamIO_get_image_d_ptr()

void* ImageStreamIO_get_image_d_ptr ( IMAGE * image )

Todo:: should this return a NULL?

Todo:: should this return a NULL?

◆ ImageStreamIO_getsemwaitindex()

int ImageStreamIO_getsemwaitindex	(	IMAGE *	image,
		int	semindexdefault
	)

Get available semaphore index.

Purpose

Get available shmim semaphore index

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	index	preferred semaphore index, if available

Parameters

[in] image the name of the shared memory file

◆ ImageStreamIO_nbSlices()

uint64_t ImageStreamIO_nbSlices ( const IMAGE * image )

inline

◆ ImageStreamIO_openIm()

errno_t ImageStreamIO_openIm	(	IMAGE *	image,
		const char *	name
	)

Connect to an existing shared memory image stream.

Wrapper for ImageStreamIO_read_sharedmem_image_toIMAGE

Parameters

[out]	image	IMAGE structure which will be attached to the existing IMAGE
[in]	name	the name of the shared memory file will be data.tmpfsdir/<name>_im.shm

◆ ImageStreamIO_read_sharedmem_image_toIMAGE()

errno_t ImageStreamIO_read_sharedmem_image_toIMAGE	(	const char *	name,
		IMAGE *	image
	)

Read / connect to existing shared memory image stream.

Purpose

Read shared memory image

Details

<

Todo:: can the following code be deleted?

Parameters

[in]	name	the name of the shared memory file to access, as in data.tmpfsdir/<name>_im.shm
[out]	image	the IMAGE structure to connect to the stream

◆ ImageStreamIO_readBufferAt()

errno_t ImageStreamIO_readBufferAt	(	const IMAGE *	image,
		const unsigned int	slice_index,
		void **	buffer
	)

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

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	indec	const int slice_index of the slice to read
[out]	buffer	void** pointer to the beginning of the slice

Returns: the error code

◆ ImageStreamIO_readLastWroteBuffer()

errno_t ImageStreamIO_readLastWroteBuffer	(	const IMAGE *	image,
		void **	buffer
	)

inline

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

Parameters

[in]	image	IMAGE* pointer to shmim
[out]	buffer	void** raw pointer where the consumer will find the last frame wrote

Returns: the error code

Parameters

[in]	image	the name of the shared memory file
[out]	buffer	raw pointer where the consumer will find the last frame wrote

◆ ImageStreamIO_readLastWroteIndex()

uint64_t ImageStreamIO_readLastWroteIndex ( const IMAGE * image )

inline

◆ ImageStreamIO_semflush()

long ImageStreamIO_semflush	(	IMAGE *	image,
		long	index
	)

Flush all semaphores of a shmim.

Purpose

Flush shmim semaphore

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	index	semaphore index flush all semaphores if index<0

Parameters

[in] image the name of the shared memory file

◆ ImageStreamIO_sempost()

long ImageStreamIO_sempost	(	IMAGE *	image,
		long	index
	)

Post all shmim semaphores.

Purpose

Posts semaphore of a shmim if index < 0, post all semaphores

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	index	semaphore index index of semaphore to be posted if index=-1, post all semaphores

Parameters

[in]	image	the name of the shared memory file
[in]	index	semaphore index

◆ ImageStreamIO_sempost_excl()

long ImageStreamIO_sempost_excl	(	IMAGE *	image,
		long	index
	)

Post all shmim semaphores except one.

Purpose

Posts all semaphores of a shmim except one

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	index	semaphore index index of semaphore to be excluded

Parameters

[in]	image	the name of the shared memory file
[in]	index	semaphore index

◆ ImageStreamIO_sempost_loop()

long ImageStreamIO_sempost_loop	(	IMAGE *	image,
		long	index,
		long	dtus
	)

Post shmim semaphores at regular time interval.

Purpose

Posts all semaphores of a shmim at regular time intervals

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	index	semaphore index is =-1, post all semaphores
[in]	dtus	time interval [us]

Parameters

[in]	image	the name of the shared memory file
[in]	index	semaphore index

◆ ImageStreamIO_semtimedwait()

int ImageStreamIO_semtimedwait	(	IMAGE *	image,
		int	index,
		const struct timespec *	semwts
	)

Parameters

[in]	image	the name of the shared memory file
[in]	index	semaphore index

◆ ImageStreamIO_semtrywait()

int ImageStreamIO_semtrywait	(	IMAGE *	image,
		int	index
	)

Parameters

[in]	image	the name of the shared memory file
[in]	index	semaphore index

◆ ImageStreamIO_semwait()

int ImageStreamIO_semwait	(	IMAGE *	image,
		int	index
	)

Wait for semaphore.

Purpose

Wait on a shmim semaphore

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[in]	index	semaphore index

Parameters

[in]	image	the name of the shared memory file
[in]	index	semaphore index

◆ ImageStreamIO_set_default_printError()

errno_t ImageStreamIO_set_default_printError ( )

Set the error reporting function to the default provided by the library.

Returns: IMAGESTREAMIO_SUCCESS on success; IMAGESTREAMIO_FAILURE on an error

◆ ImageStreamIO_set_printError()

errno_t ImageStreamIO_set_printError ( errno_t(*)(const char *, const char *, int, errno_t, char *) new_printError )

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.

Parameters

new_printError is a pointer to the function to use for reporting errors. Can be NULL.

Returns: IMAGESTREAMIO_SUCCESS on success; IMAGESTREAMIO_FAILURE on an error

◆ ImageStreamIO_typesize()

int ImageStreamIO_typesize ( uint8_t atype )

Get the size in bytes from the data type code.

Returns: the size in bytes of the data type if valid; -1 if atype is not valid

Parameters

[in] atype the type code (see ImageStruct.h

◆ ImageStreamIO_writeBuffer()

errno_t ImageStreamIO_writeBuffer	(	const IMAGE *	image,
		void **	buffer
	)

inline

Get the raw pointer where the producer should write.

Purpose

Return the raw pointer where the producer should write

Arguments

Parameters

[in]	image	IMAGE* pointer to shmim
[out]	buffer	void** raw pointer where the producer should write

Returns: the error code

Parameters

[in]	image	the name of the shared memory file
[out]	buffer	raw pointer where the producer should write

◆ ImageStreamIO_writeIndex()

uint64_t ImageStreamIO_writeIndex ( const IMAGE * image )

inline

◆ init_ImageStreamIO()

errno_t init_ImageStreamIO ( )

Functions

Detailed Description

Function Documentation

◆ __attribute__()

◆ ImageStreamIO_bitpix()

◆ ImageStreamIO_closeIm()

◆ ImageStreamIO_createIm()

◆ ImageStreamIO_createIm_gpu()

◆ ImageStreamIO_createsem()

Purpose

Arguments

◆ ImageStreamIO_destroyIm()

◆ ImageStreamIO_destroysem()

Purpose

Arguments

◆ ImageStreamIO_filename()

◆ ImageStreamIO_get_image_d_ptr()

◆ ImageStreamIO_getsemwaitindex()

Purpose

Arguments

◆ ImageStreamIO_nbSlices()

◆ ImageStreamIO_openIm()

◆ ImageStreamIO_read_sharedmem_image_toIMAGE()

Purpose

Details

◆ ImageStreamIO_readBufferAt()

Purpose

Arguments

◆ ImageStreamIO_readLastWroteBuffer()

Purpose

Arguments

◆ ImageStreamIO_readLastWroteIndex()

◆ ImageStreamIO_semflush()

Purpose

Arguments

◆ ImageStreamIO_sempost()

Purpose

Arguments

◆ ImageStreamIO_sempost_excl()

Purpose

Arguments

◆ ImageStreamIO_sempost_loop()

Purpose

Arguments

◆ ImageStreamIO_semtimedwait()

◆ ImageStreamIO_semtrywait()

◆ ImageStreamIO_semwait()

Purpose

Arguments

◆ ImageStreamIO_set_default_printError()

◆ ImageStreamIO_set_printError()

◆ ImageStreamIO_typesize()

◆ ImageStreamIO_writeBuffer()

Purpose

Arguments

◆ ImageStreamIO_writeIndex()

◆ init_ImageStreamIO()

◆ attribute()