API_SprLibInternal::lib::core

Collaboration diagram for API_SprLibInternal::lib::core:

Data Structures
class	SprStreamFile
	Stream object that refers to classical file descriptors. More...
class	SprStreamNull
	Stream object that refers to the null device. More...
class	SprStreamBuf
	Stream object that refers to the null device. More...
class	SprStreamDynBuf
	Stream object that refers to a dynamically allocated buffer. More...
class	SprStreamDynStr
	Stream object that refers to a dynamic string. More...

Namespaces
	xref_spr_ini_fini
	Module initilisation and finalisation
	xref_spr_class
	Working with SPRAAK classes and objects

Modules
	API_SprLibInternal::lib::core::filefmt

Macros
#define	SPR_DT_ENUM_INITIALIZER(name, str_tbl)
#define	SPR_INI_DEP(dep_mod_name)
#define	SPR_INI_MOD(mod_name, ini_func, fini_func, dep_lst)
#define	SPR_DEFAULT_FORMAT
#define	SPR_DEFAULT_FORMAT_STR
#define	spr_assert1(routine__, tst__)
#define	spr_assert2(routine__, tst__)
#define	spr_assert3(routine__, tst__)

Typedefs
typedef int(*	SprDT_read1 )(const SprDT *restrict dt, SprStream *restrict fd, void *restrict dst)
typedef int(*	SprDT_write1 )(const SprDT *restrict dt, SprStream *restrict fd, const void *restrict src)
typedef char *(*	SprDT_str_cvt )(const SprDT *restrict dt, void *restrict dst, const char *restrict str)
typedef void(*	SprDT_free )(const SprDT *restrict dt, void *restrict ptr)
typedef void *(*	SprDT_cpy )(const SprDT *restrict dt, void *restrict dst, const void *restrict src)
typedef SprDynStr(*	SprDT_str )(const SprDT *restrict dt, const void *restrict src)
typedef ssize_t(*	SprDT_print )(const SprDT *restrict dt, SprStream *restrict fd, const void *restrict src)
typedef struct SprIniDep	SprIniDep
typedef struct SprIniMod	SprIniMod

Functions
int	spr_atomic_slot_acquire0_nowait (SprAtomicSlot *slot)
void	spr_atomic_slot_signal_ready (SprAtomicSlot *slot, int ndx)
int	spr_atomic_slot_signal_ready_acquire0_nowait (SprAtomicSlot *slot, int ndx)
void	spr_atomic_slot_release (SprAtomicSlot *slot, int ndx)
void	spr_atomic_slot_release0 (SprAtomicSlot *slot)
	Release slot 0. More...
uint32_t	spr_atomic_slot_release_nocheck (SprAtomicSlot *slot, int ndx)
void	spr_atomic_slot_release0_check (SprAtomicSlot *slot)
int	spr_atomic_slot_release_check0 (SprAtomicSlot *slot, int ndx)
void	spr_atomic_slot_release_all (SprAtomicSlot *slot)
char *	spr_ctime (const time_t *timep, char *buf, size_t sz)
struct tm *	spr_gmtime (const time_t *timep, struct tm *result)
char *	spr_f64_to_str (char buf[32], double x)
char *	spr_f32_to_str (char buf[16], float x)
void	spr_dt_free (const SprDT *restrict dt, void *restrict ptr)
void	spr_dt_alloc_free (const SprDT *restrict dt, void *restrict ptr)
	Free for simple allocated objects. More...
size_t	spr_dynmem_item_cnt (void)
size_t	spr_dynmem_byte_cnt (void)
void	spr_hexdump2buf (char *dst, const void *data, size_t size)
int	spr_dynmem_dump (SprStream *fd)
	Dump the data that is still allocated to file fd. This routine is not mult-threading safe. More...
const char *	spr_str_no_empty (const char *str, const char *str_empty)
void	spr_dynmem_cfg (int mode)
int	spr_hash_strlin_searchn (const char *restrict const hlst[], int Nel, const char *restrict str)
int	spr_ini_register (SprIniMod *curr_mod)
int	spr_ini_resolve (void)
int	spr_kset_enohdr_adjust (SprStream *restrict fd)
SprKeySet *	spr_kset_read_spraak (SprStream *restrict fd, SprKeySet *restrict keys)
int	spr_kset_write_spraak (SprStream *restrict fd, SprKeySet *restrict keys, int mode)
SprKeySet *	spr_kset_read_key (SprStream *restrict fd, SprKeySet *restrict keys)
int	spr_kset_write_key (SprStream *restrict fd, SprKeySet *restrict keys, int mode)
int	spr_kset_stream_adjust_close (SprStream *restrict fd, ssize_t dim1)
void	spr_msg_set_timeout (int sec)
int	spr_msg_ini_time (SprMsgId *prog)
SprSrmEl *	spr_srm_check (const SprSrmEl *srm_el)
SprStream *	spr_stream_close_check_auto (SprStream *restrict fd, SprMsgId *restrict routine)
SprStream *	spr_stream_nullqw_make (SprStreamNull *restrict fd)
off_t	spr_stream_buf_tell (SprStreamBuf *restrict fd)
SprStream *	spr_stream_buf_make (const char *name, uint8_t *buf, size_t size, size_t fill, unsigned int flags, SprKeySet *keys)
SprStream *	spr_stream_bufqr_make (SprStreamBuf *restrict fd, const char *restrict buf, size_t size)
const void *	spr_stream_buf_get (SprStreamBuf *fd)
void	spr_stream_buf_rewind (SprStreamBuf *fd)
void *	spr_stream_dynbuf_close_getdata (SprStreamDynBuf *restrict fd)
SprDynStr	spr_stream_dynstr_close_getdata (SprStreamDynStr *restrict fd)
void *	spr_stream_dynbufq_close (SprStreamDynBuf *restrict fd)
SprDynStr	spr_stream_dynstrq_close (SprStreamDynStr *restrict fd)
SprStream *	spr_stream_dynbufq_make (SprStreamDynBuf *restrict fd, void *restrict buf, size_t alen, size_t fill)
SprStream *	spr_stream_dynstrq_make (SprStreamDynStr *restrict fd, SprDynStr str, size_t fill)
size_t	spr_strlenq (const char *restrict str)
size_t	spr_strlenoq (const char *restrict str)

Variables
const char *	spr_ini_fail

Detailed Description

Macro Definition Documentation

#define SPR_DT_ENUM_INITIALIZER	(		name,
			str_tbl
	)

Initialize some static enumeration type. The static means that but the type and the NULL terminated array of strings will exist for as long as the enumeration type is needed, and that neither must be explicitely freed.
The name argument specifies the string respresentation (used in file headers, messages, ...) that will be used for this type. Typically this is of the form "ENUM_...".
The str_tbl is the NULL terminated list of string giving the possible different values. The string are mapped to 0...(#strings-1). There is (currently) no provision to map to strings to the same number, to allow gaps in the numbering or to allow negative numbers.
Code example:

static const char *const digit_str =
 {"ZERO","ONE","TWO","THREE","FOUR","FIVE","SIX","SEVEN","EIGHT","NINE",NULL};
static SprDT_EnumT spr_dt_tf[1] = {SPR_DT_ET_INITIALIZER("DIGIT",digit_str)};

#define SPR_INI_DEP

(

dep_mod_name

)

Initialize an element in the dependency list (of the type SprIniDep). See Module initilisation and finalisation for an example.

#define SPR_INI_MOD	(		mod_name,
			ini_func,
			fini_func,
			dep_lst
	)

Initialize the main dependecy structure (of the type SprIniMod). See Module initilisation and finalisation for an example.

#define SPR_DEFAULT_FORMAT

#define SPR_DEFAULT_FORMAT_STR

#define spr_assert1	(		routine__,
			tst__
	)

#define spr_assert2	(		routine__,
			tst__
	)

#define spr_assert3	(		routine__,
			tst__
	)

Typedef Documentation

typedef int(* SprDT_read1)(const SprDT *restrict dt, SprStream *restrict fd, void *restrict dst)

typedef int(* SprDT_write1)(const SprDT *restrict dt, SprStream *restrict fd, const void *restrict src)

typedef char*(* SprDT_str_cvt)(const SprDT *restrict dt, void *restrict dst, const char *restrict str)

typedef void(* SprDT_free)(const SprDT *restrict dt, void *restrict ptr)

typedef void*(* SprDT_cpy)(const SprDT *restrict dt, void *restrict dst, const void *restrict src)

typedef SprDynStr(* SprDT_str)(const SprDT *restrict dt, const void *restrict src)

typedef ssize_t(* SprDT_print)(const SprDT *restrict dt, SprStream *restrict fd, const void *restrict src)

typedef struct SprIniDep SprIniDep

Opaque type needed to create a dependency for ini or fini routine. See Module initilisation and finalisation for more details.

typedef struct SprIniMod SprIniMod

Opaque type needed to create a dependency for ini or fini routine. See Module initilisation and finalisation for more details.

Function Documentation

int spr_atomic_slot_acquire0_nowait

(

SprAtomicSlot *

slot

)

Try to get slot 0.

Returns

1 if slot 0 was acquired and 0 otherwise.

void spr_atomic_slot_signal_ready	(	SprAtomicSlot *	slot,
		int	ndx
	)

Signal that a previously acquired slot is ready for further processing.

int spr_atomic_slot_signal_ready_acquire0_nowait	(	SprAtomicSlot *	slot,
		int	ndx
	)

Signal that a previously acquired slot is ready and try to aquire slot 0 (to further process the content of slot ndx and any other slot that is ready).

Returns

1 if slot 0 was acquired, 0 otherwise.

void spr_atomic_slot_release	(	SprAtomicSlot *	slot,
		int	ndx
	)

Clear the ready flag for a previously acquired slot and release the slot (for reuse).

void spr_atomic_slot_release0

(

SprAtomicSlot *

slot

)

Release slot 0.

uint32_t spr_atomic_slot_release_nocheck	(	SprAtomicSlot *	slot,
		int	ndx
	)

Clear the ready flag for a previously acquired slot and release the slot (for reuse). Do not check for waiting threads.

Returns

A bit mask indicating any other slots that are ready.

void spr_atomic_slot_release0_check

(

SprAtomicSlot *

slot

)

Do the checking part after a series of spr_atomic_slot_release_nocheck() calls.

int spr_atomic_slot_release_check0	(	SprAtomicSlot *	slot,
		int	ndx
	)

Clear the ready flag for a previously acquired slot and release the slot (for reuse). This routine should only be used when the caller has acquired slot 0 (the real resource).

Returns

The slot->read_msk after the update, i.e. one can check if there are still pending items.

void spr_atomic_slot_release_all

(

SprAtomicSlot *

slot

)

Release all slots.

Note

Should only be used in conjunction with spr_atomic_slot_acquire_all().

char* spr_ctime	(	const time_t *	timep,
		char *	buf,
		size_t	sz
	)

Replaces the ctime() function in a thread-safe fashion by writing the result to the buffer buf of length sz.

struct tm* spr_gmtime	(	const time_t *	timep,
		struct tm *	result
	)

Replaces the gmtime() function in a thread-safe fashion by writing the result to the buffer result.

char* spr_f64_to_str	(	char	buf[32],
		double	x
	)

Make a standardized numeric representation of the given double x and write it to buf. Should be very similar to sprintf(buf,"\%.15\#g",x).

Returns

Pointer to the terminating '\0' in buf.

Note

buf must be at least 32 bytes long to accomodate for a 15 decimal digits mantissa, a sign, a decimal point, an exponent and a terminating '\0'.

char* spr_f32_to_str	(	char	buf[16],
		float	x
	)

Make a standardized numeric representation of the given float x and write it to buf. Should be very similar to sprintf(buf,"\%.6\#g",x).

Returns

Pointer to the terminating '\0' in buf.

Note

buf must be at least 24 bytes long to accomodate for a 6 decimal digits mantissa, a sign, a decimal point, an exponent and a terminating '\0'.

void spr_dt_free	(	const SprDT *restrict	dt,
		void *restrict	ptr
	)

Release all memory associated to the object of type dt located at address ptr.

Note

This method typically equals NULL (and hence cannot be called) since most types do not allocate their own memory. So check the dt->free_fp pointer before calling this method!

void spr_dt_alloc_free	(	const SprDT *restrict	dt,
		void *restrict	ptr
	)

Free for simple allocated objects.

size_t spr_dynmem_item_cnt

(

void

)

Return the total number of items allocated (and not yet freed). The count also includes the dynamically sized strings and the structures needed for the large pools of identical sized items.

Returns

The total number of items allocated (and not yet freed).

size_t spr_dynmem_byte_cnt

(

void

)

Return the total number of bytes allocated (and not yet freed). The count also includes the dynamically sized strings (which are typically over-allocated) and the structures needed for the large pools of identical sized items. The returned value is only accurate if the accounting system is active.

Returns

The total number of bytes allocated (and not yet freed).

void spr_hexdump2buf	(	char *	dst,
		const void *	data,
		size_t	size
	)

Auxilary routine for hexdumping data to the message system (via a temporary buffer).

Parameters

dst	String to print the hexdump to (must be 60 characters long).
data	The data to dump.
size	The number of bytes to dump (will be clipped to 16 bytes).

int spr_dynmem_dump

(

SprStream *

fd

)

Dump the data that is still allocated to file fd. This routine is not mult-threading safe.

it should only be called from the main thread after all helper threads have stopped or are idling.

Returns

(-1) if the data could not be written and 0 otherwise.

Parameters

fd	File to dump the data to.

const char* spr_str_no_empty	(	const char *	str,
		const char *	str_empty
	)

Returns

The given string str or str_empty if str is NULL or str equals the empty string.

Parameters

str	String to check.
str_empty	Alternative.

void spr_dynmem_cfg

(

int

mode

)

Set the amount of accounting and checking for the dynamic memory management sub-system in SPRAAK. The mode can be set to the following values:

0 (standard)

Report allocation failures and count how many items are allocated. This allows the detection of memory leaks.

1 (count)

On top of the standard mode, also track each allocated item by pointer value and the number of bytes allocated. This allows the detection of double free's and provides some more details on memory leaks (pointers and sizes).

* (verif)

On top of the counting mode, track each allocated item by name (item, routine and thread) and add some slack space before and after each allocated item in order to allow testing for simple buffer overrun errors. This allows details analysis of memory leaks, double free's and a crude (*) detection of simple buffer overrun errors.
(*) Buffer overrun is not detected when it occurs, only when the item is freed or reallocated. The protection only covers a few bytes before and after each item.

Note

This routine is called autmatically, either when the '–check_dynmem <lvl>' option is specified when calling a program or by setting the 'SPR_DYNMEM_CHECK' environment variable.

One should never manually call the routine: this routine should only be called once and this before the very first item is allocated and spraak_ini() or spraak_ini_prog() already call this routine.

Parameters

mode	Amount of accounting and checking requested.

int spr_hash_strlin_searchn	(	const char *restrict const	hlst[],
		int	Nel,
		const char *restrict	str
	)

Lookup string str in the lookup table (a list of strings) hlst. Nel is the number of elements in the array hlst. If Nel equals -1, the lookup table is assumed to be NULL terminated. A string str matches an entry in hlst if all its characters up till but not including the terminating '\0' match with hlst[ndx], i.e. if memcpy(str,hlst[ndx],strlen(str)) equals 0. An addition contraint is that only one entry in hlst may match.

Returns

The index at which str was found in the lookup table hlst, or -1 if the string could not be located or if there were multiple matches.

Note

No warning is given when the string is not found.

Deprecated:

Allowing partial matches isn't future proof, so avoid this routine

int spr_ini_register

(

SprIniMod *

curr_mod

)

int spr_ini_resolve

(

void

)

int spr_kset_enohdr_adjust

(

SprStream *restrict

fd

)

Adjust the dimension keys when reading from a disk based file with no (or an external) header.

Returns

0 on success, 1 if the length of the file could not be derived, and -1 on error.

SprKeySet* spr_kset_read_spraak	(	SprStream *restrict	fd,
		SprKeySet *restrict	keys
	)

Read the key-set keys from the open stream fd using the SPRAAK-header format. The stream must be in read mode and the read pointer should be positioned right after (or right before) the magic word (file header indicator). If keys equals NULL, the keyset internal to fd will be used (which will be allocated if needed). In other words, the only way to use a keyset different to the one inside fd is by specifying a non NULL keys argument.

Returns

The key-set on success and (NULL) on failure.

Note

On success, the new size of the header is stored in the appropriate field in the key-set.

On failure, a key-set given as input argument will not be freed.

int spr_kset_write_spraak	(	SprStream *restrict	fd,
		SprKeySet *restrict	keys,
		int	mode
	)

Write the key-set keys to the open stream fd using the SPRAAK-header format. If keys equals NULL, the keyset internal to fd will be used. The flag mode determines how much space the header may occupy on disk:

SPR_KSET_MODE_FIT

the same amount space as from where the key-set was read (or to where it was last written to),

SPR_KSET_MODE_FIT_ERR

the same as SPR_KSET_MODE_FIT, but give an error if the header does not fit,

SPR_KSET_MODE_MIN

a minimal amount of space,

SPR_KSET_MODE_STD

a well spaced format with the size rounded to a 64-bytes boundary and with at least 96 bytes of free space for new keys.

Returns

0 on success, (-1) on failure, and the required space needed if mode equals SPR_KSET_MODE_FIT and the header could not be written in the available space.

Note

On success, the new size of the header is stored in the appropriate field in the key-set.

SprKeySet* spr_kset_read_key	(	SprStream *restrict	fd,
		SprKeySet *restrict	keys
	)

Read the key-set keys from the open stream fd using the key-header format. The stream must be in read mode and the read pointer should be positioned right after (or right before) the magic word (file header indicator). If keys equals NULL, the keyset internal to fd will be used (which will be allocated if needed). In other words, the only way to use a keyset different to the one inside fd is by specifying a non NULL keys argument.

Returns

The key-set on success and (NULL) on failure.

Note

On success, the new size of the header is stored in the appropriate field in the key-set.

On failure, a key-set given as input argument will not be freed.

int spr_kset_write_key	(	SprStream *restrict	fd,
		SprKeySet *restrict	keys,
		int	mode
	)

Write the key-set keys to the open stream fd using the key-header format. If keys equals NULL, the keyset internal to fd will be used. The flag mode determines how much space the header may occupy on disk:

SPR_KSET_MODE_FIT

the same amount space as from where the key-set was read (or to where it was last written to),

SPR_KSET_MODE_FIT_ERR

the same as SPR_KSET_MODE_FIT, but give an error if the header does not fit,

SPR_KSET_MODE_MIN

a minimal amount of space,

SPR_KSET_MODE_STD

a well spaced format with the size rounded to a 64-bytes boundary and with at least 96 bytes of free space for new keys.

Returns

0 on success, (-1) on failure, and the required space needed if mode equals SPR_KSET_MODE_FIT and the header could not be written in the available space.

Note

On success, the new size of the header is stored in the appropriate field in the key-set.

int spr_kset_stream_adjust_close	(	SprStream *restrict	fd,
		ssize_t	dim1
	)

Adjust the key DIM1 to its new value, try to adjust the header on the media and close the stream. See spr_kset_set_value_dim1(), spr_kset_stream_modif() and spr_stream_close() for more details.

Returns

0 on success and -1 on failure.

void spr_msg_set_timeout

(

int

sec

)

Allow the message system to timeout. A value of 0 disables the timing out the message system. Any other value will timeout the message system after sec seconds starting from when this routine was called;

Parameters

sec	Timeout value in seconds

int spr_msg_ini_time

(

SprMsgId *

prog

)

SprSrmEl* spr_srm_check

(

const SprSrmEl *

srm_el

)

Check if the shared resource srm_el is present in the hash table (the table must be in a locked state!!!).

Returns

The srm-el or NULL if not found.

Parameters

srm_el

Shared resource.

SprStream* spr_stream_close_check_auto	(	SprStream *restrict	fd,
		SprMsgId *restrict	routine
	)

Remove the file from the auto-removal queue.

Note

This routine should only be called when fd->auto_link!=NULL.

This routine should be called after closing the file but before freeing the file name or any other components making op the basic stream structure.

The field fd->fname must be a fully qualified path to the file (may be solved in future versions)!

SprStream* spr_stream_nullqw_make

(

SprStreamNull *restrict

fd

)

Quickly initialize the '/dev/null' stream fd for writing.

Returns

The initialized stream handle.

Note

There is no need to close the stream when it is no longer needed.

off_t spr_stream_buf_tell

(

SprStreamBuf *restrict

fd

)

SprStream* spr_stream_buf_make	(	const char *	name,
		uint8_t *	buf,
		size_t	size,
		size_t	fill,
		unsigned int	flags,
		SprKeySet *	keys
	)

Create a stream named name that maps to a static data buffer buf of length size. The buffer is already filled with data up till position fill. The flags and keys arguments behave identically as in spr_stream_open().

Returns

The newly created stream handle or (NULL) on error.

Note

The name argument must point to data that will be persistent for as long as this stream is in use (i.e. not closed).

SprStream* spr_stream_bufqr_make	(	SprStreamBuf *restrict	fd,
		const char *restrict	buf,
		size_t	size
	)

Quickly initialize the stream fd for reading (ASCII mode) from the buffer buf assuming a length of size bytes.

Returns

The initialized stream handle.

Note

From this call on the buffer buf belong to the stream and hence should not be used for any other purpose till the stream is no longer needed (there is no need to close it).

const void* spr_stream_buf_get

(

SprStreamBuf *

fd

)

Get the content of the static buffer (after flushing all pending write data).

void spr_stream_buf_rewind

(

SprStreamBuf *

fd

)

void* spr_stream_dynbuf_close_getdata

(

SprStreamDynBuf *restrict

fd

)

Close the dynamic buffer stream and return the dynamically allocated buffer.

Returns

The dynamically allocated buffer or (NULL) on error.

Note

If one did only read operations, the buffer will be unmodified. If one did write operations as well, the buffer will be modified and/or reallocated and or set to NULL (on error).

Do not forget the terminating '\0' when creating a string.

SprDynStr spr_stream_dynstr_close_getdata

(

SprStreamDynStr *restrict

fd

)

Close the dynamic string buffer stream and return the dynamic string.

Returns

The dynmic string or (NULL) on error.

Note

If one did only read operations, the string will be unmodified. If one did write operations as well, the string will be modified and/or reallocated and or set to NULL (on error).

Do not forget the terminating '\0' when writing to the string.

void* spr_stream_dynbufq_close

(

SprStreamDynBuf *restrict

fd

)

Close the 'quick' dynamic buffer stream and return the dynamic buffer.

Returns

The dynmically allocated buffer or (NULL) on error.

Note

Do not forget the terminating '\0' when creating a string.

One can use SprStreamDynBuf::tell() to find out the length of the dynamic string.

SprDynStr spr_stream_dynstrq_close

(

SprStreamDynStr *restrict

fd

)

Close the 'quick' dynamic string buffer stream and return the dynamic string.

Returns

The dynmic string or (NULL) on error.

Note

Do not forget the terminating '\0' when writing to the string.

One can use SprStreamDynBuf::tell() to find out the length of the dynamic string.

SprStream* spr_stream_dynbufq_make	(	SprStreamDynBuf *restrict	fd,
		void *restrict	buf,
		size_t	alen,
		size_t	fill
	)

Quickly initialize the stream fd for writing (ASCII mode) to the dynamically allocated buffer buf of size alen assuming fill characters/bytes are already filled in.

Returns

The initialized stream handle.

Note

From this call on the dynamic buffer belong to the stream and hence should not be used for any other purpose. At the end of the stream operations, the (modified) dynamic buffer should be reclaimed using the spr_stream_dynbufq_close() function.

SprStream* spr_stream_dynstrq_make	(	SprStreamDynStr *restrict	fd,
		SprDynStr	str,
		size_t	fill
	)

Quickly initialize the stream fd for writing (ASCII mode) to the dynamic string str assuming fill characters/bytes are already filled in.

Returns

The initialized stream handle.

Note

From this call on the dynamic string belong to the stream and hence should not be used for any other purpose. At the end of the stream operations, the (modified) dynamic string should be reclaimed using the spr_stream_dynstrq_close() function.

size_t spr_strlenq

(

const char *restrict

str

)

Determine the length of a string when it would be converted to a quoted string.

Returns

The quoted string length.

size_t spr_strlenoq

(

const char *restrict

str

)

Determine the length of a string when it would be optionally (i.e. if required for proper reading) converted to a quoted string.

Returns

The (un)quoted string length.

Variable Documentation

const char* spr_ini_fail

Since initialisation and finalisation routines cannot return any values, error conditions are collected in this variable. See Module initilisation and finalisation for an example.