This file contains the declarations for OS functions for creating/managing/freeing threads, semaphores, mutexes, critical sections, signals, memory and sockets. There are also abstractions for atomic operations as well as some time, sleep and string operations. These definitions in this module are here to account for differences between Linux and Windows. More...

#include <netinet/in.h>
#include <pthread.h>
#include <semaphore.h>
#include <signal.h>
#include <string.h>
#include <strings.h>
#include <unistd.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <time.h>
#include "cdi_utility_api.h"

Data Structures
struct	CdiSignalHandlerInfo
	Structure used to hold signal handler data. More...

Macros
#define	CDI_STDIN stdin
	Definition of OS agnostic standard input stream.

#define	CDI_STDOUT stdout
	Definition of OS agnostic standard output stream.

#define	CDI_STDERR stderr
	Definition of OS agnostic standard error output stream.

#define	CDI_STDIN_FILENO STDIN_FILENO
	Definition of OS agnostic standard input file number.

#define	CDI_STDOUT_FILENO STDOUT_FILENO
	Definition of OS agnostic standard output file number.

#define	CDI_STDERR_FILENO STDERR_FILENO
	Definition of OS agnostic standard error file number.

#define	CDI_THREAD_PARAM void*
	Define portable thread function parameter type.

#define	CDI_THREAD int
	Define portable thread function return type.

#define	CDI_INFINITE 0xFFFFFFFF
	Infinity used as wait arguments, i.e "wait for infinity".

#define	CdiOsAtomicInc16(x) __sync_add_and_fetch((x), 1)
	Atomic increment a 16-bit value by 1 (matches windows variant, which uses functions).

#define	CdiOsAtomicDec16(x) __sync_sub_and_fetch((x), 1)
	Atomic decrement a 16-bit value by 1 (matches windows variant, which uses functions).

#define	CdiOsAtomicRead16(x) __sync_add_and_fetch((x), 0)
	Atomic read a 16-bit value (matches windows variant, which uses functions).

#define	CdiOsAtomicAdd16(x, b) __sync_add_and_fetch((x), (b))
	Atomic add a 16-bit value by a 16-bit value sent (matches windows variant, which uses functions).

#define	CdiOsAtomicInc32(x) __sync_add_and_fetch((x), 1)
	Atomic increment a 32-bit value by 1 (matches windows variant, which uses functions).

#define	CdiOsAtomicDec32(x) __sync_sub_and_fetch((x), 1)
	Atomic decrement a 32-bit value by 1 (matches windows variant, which uses functions).

#define	CdiOsAtomicRead32(x) __sync_add_and_fetch((x), 0)
	Atomic read a 32-bit value (matches windows variant, which uses functions).

#define	CdiOsAtomicAdd32(x, b) __sync_add_and_fetch((x), (b))
	Atomic add a 32-bit value by a 32-bit value sent (matches windows variant, which uses functions).

#define	CdiOsAtomicInc64(x) __sync_add_and_fetch((x), 1)
	Atomic increment a 64-bit value by 1 (matches windows variant, which uses functions).

#define	CdiOsAtomicDec64(x) __sync_sub_and_fetch((x), 1)
	Atomic decrement a 64-bit value by 1 (matches windows variant, which uses functions).

#define	CdiOsAtomicRead64(x) __sync_add_and_fetch((x), 0)
	Atomic read a 64-bit value (matches windows variant, which uses functions).

#define	CdiOsAtomicAdd64(x, b) __sync_add_and_fetch((x), (b))
	Atomic add a 64-bit value by a 64-bit value sent (matches windows variant, which uses functions).

#define	CdiOsAtomicLoad16(x) __atomic_load_n((x), __ATOMIC_CONSUME)
	Atomic load value. Valid memory models are:

#define	CdiOsAtomicLoad32(x) __atomic_load_n((x), __ATOMIC_CONSUME)
	32-bit version of CdiOsAtomicLoad16 (matches windows variant, which uses functions).

#define	CdiOsAtomicLoad64(x) __atomic_load_n((x), __ATOMIC_CONSUME)
	64-bit version of CdiOsAtomicLoad16 (matches windows variant, which uses functions).

#define	CdiOsAtomicLoadPointer(x) __atomic_load_n((x), __ATOMIC_CONSUME)
	Pointer version of CdiOsAtomicLoad16 (matches windows variant, which uses functions).

#define	CdiOsAtomicStore16(x, v) __atomic_store_n((x), (v), __ATOMIC_RELEASE)
	Atomic store value. Valid memory models are:

#define	CdiOsAtomicStore32(x, v) __atomic_store_n((x), (v), __ATOMIC_RELEASE)
	32-bit version of CdiOsAtomicStore16 (matches windows variant, which uses functions).

#define	CdiOsAtomicStore64(x, v) __atomic_store_n((x), (v), __ATOMIC_RELEASE)
	64-bit version of CdiOsAtomicStore16 (matches windows variant, which uses functions).

#define	CdiOsAtomicStorePointer(x, v) __atomic_store_n((x), (v), __ATOMIC_RELEASE)
	Pointer version of CdiOsAtomicStore16 (matches windows variant, which uses functions).

#define	CDI_INVALID_HANDLE_VALUE -1
	Define portable invalid handle.

#define	CDI_STATIC_MUTEX_INITIALIZER PTHREAD_MUTEX_INITIALIZER
	Initialization value used to initialize the value of a static mutex variable.

#define	CdiOsStaticMutexLock(x) pthread_mutex_lock(&(x))
	Lock a statically generated mutex.

#define	CdiOsStaticMutexUnlock(x) pthread_mutex_unlock(&(x))
	Unlock a statically generated mutex.

#define	CDI_HUGE_PAGES_BYTE_SIZE (2 * 1024 * 1024)
	Size of huge pages. Memory must be a multiple of this size when using the CdiOsMemAllocHugePage() and CdiOsMemFreeHugePage() APIs. NOTE: Must match the "Hugepagesize" setting in /proc/meminfo.

#define	CDI_STATIC_ASSERT(condition, message) _Static_assert(condition, message)
	Macro used to halt due to condition not being met during compile time. NOTE: Depending on GCC version, an assert failure may not use the specified message and instead generate an error similar to this: "error: negative width in bit-field ‘__error_if_negative". In this case, to see the specified message, see the next error in the compiler output.

#define	CDI_MAX_THREAD_NAME (50)
	Maximum thread name size.

#define	CDI_OS_SIG_TIMEOUT (0xFFFFFFFF)
	Timeout value returned when waiting on a signal using CdiOsSignalsWait().

#define	CDI_MAX_WAIT_MULTIPLE (64)
	Maximum number of signals that can be passed to CdiOsSignalsWait().

#define	CDI_OS_SOCKET_MAX_IOVCNT (10)
	The maximum size of iovec array that can be passed in to CdiOsSocketWrite().

#define	CDI_MAX_SIGNAL_HANDLERS (10)
	Maximum number of signal handlers.

#define	CDI_MAX_FORMATTED_TIMEZONE_STRING_LENGTH (128)
	Maximum length of a single formatted time string.

#define	CdiOsStrTokR strtok_r
	< get a string token

#define	CdiOsStrNCaseCmp strncasecmp
	Used to compare two strings specifying the number of characters to compare, ignoring the case of the characters.

#define	CdiOsStrCaseCmp strcasecmp
	Used to compare two strings, ignoring the case of the characters.

#define	CdiOsStrCmp strcmp
	Used to compare two strings.

#define	CdiOsStrNCmp strncmp
	Used to compare two strings specifying the number of characters to compare.

#define	CdiOsGetMilliseconds() (CdiOsGetMicroseconds()/1000)
	Macro to get OS time in milliseconds that uses CdiOsGetMicroseconds().

Typedefs
typedef CDI_THREAD(*	CdiThreadFuncName) (CDI_THREAD_PARAM)
	Define portable thread function.

typedef pthread_key_t	CdiThreadData
	Define portable thread data type.

typedef sem_t *	CdiSemID
	Define portable semaphore.

typedef struct CdiSignalType_t *	CdiSignalType
	Define portable signal type. Don't use void* here, which prevents the compiler from type checking.

typedef pthread_mutex_t *	CdiCsID
	Define portable critical section.

typedef FILE *	CdiFileID
	Define portable File ID type.

typedef pthread_mutex_t	CdiStaticMutexType
	Define portable static mutex type. An example implementation:

typedef void(*	CdiSignalHandlerFunction) (int sig, siginfo_t siginfo, void context)
	Type used for signal handler.

typedef struct CdiThreadID_t *	CdiThreadID
	Define portable thread type. Separate name from type, otherwise the typedef that follows it will generate a compile error (duplicate typedef).

typedef struct CdiSocket_t *	CdiSocket
	Define portable socket type.

Functions
CDI_INTERFACE void	CdiOsUseLogger (void)

CDI_INTERFACE bool	CdiOsSignalHandlerSet (int signal_num, CdiSignalHandlerFunction func_ptr)

CDI_INTERFACE bool	CdiOsThreadCreatePinned (CdiThreadFuncName thread_func, CdiThreadID thread_id_out_ptr, const char thread_name_str, void *thread_func_arg_ptr, CdiSignalType start_signal, int cpu_affinity)

static bool	CdiOsThreadCreate (CdiThreadFuncName thread_func, CdiThreadID thread_id_out_ptr, const char thread_name_str, void *thread_func_arg_ptr, CdiSignalType start_signal)

CDI_INTERFACE bool	CdiOsThreadAllocData (CdiThreadData *handle_out_ptr)

CDI_INTERFACE bool	CdiOsThreadFreeData (CdiThreadData handle)

CDI_INTERFACE bool	CdiOsThreadSetData (CdiThreadData handle, void *content_ptr)

CDI_INTERFACE bool	CdiOsThreadGetData (CdiThreadData handle, void **content_out_ptr)

CDI_INTERFACE const char *	CdiOsThreadGetName (CdiThreadID thread_id)

CDI_INTERFACE bool	CdiOsThreadJoin (CdiThreadID thread_id, uint32_t timeout_in_ms, bool *timed_out_ptr)

CDI_INTERFACE bool	CdiOsSemaphoreCreate (CdiSemID *ret_sem_handle_ptr, int sem_count)

CDI_INTERFACE bool	CdiOsSemaphoreDelete (CdiSemID sem_handle)

CDI_INTERFACE bool	CdiOsSemaphoreRelease (CdiSemID sem_handle)

CDI_INTERFACE bool	CdiOsSemaphoreReserve (CdiSemID sem_handle, int timeout_in_ms)

CDI_INTERFACE int	CdiOsSemaphoreValueGet (CdiSemID sem_handle)

CDI_INTERFACE bool	CdiOsCritSectionCreate (CdiCsID *cs_handle_ptr)

CDI_INTERFACE void	CdiOsCritSectionReserve (CdiCsID cs_handle)

CDI_INTERFACE void	CdiOsCritSectionRelease (CdiCsID cs_handle)

CDI_INTERFACE bool	CdiOsCritSectionDelete (CdiCsID cs_handle)

CDI_INTERFACE bool	CdiOsSignalCreate (CdiSignalType *signal_handle_ptr)

CDI_INTERFACE bool	CdiOsSignalDelete (CdiSignalType signal_handle)

CDI_INTERFACE bool	CdiOsSignalClear (CdiSignalType signal_handle)

CDI_INTERFACE bool	CdiOsSignalSet (CdiSignalType signal_handle)

CDI_INTERFACE bool	CdiOsSignalGet (CdiSignalType signal_handle)

CDI_INTERFACE bool	CdiOsSignalReadState (CdiSignalType signal_handle)

CDI_INTERFACE bool	CdiOsSignalWait (CdiSignalType signal_handle, uint32_t timeout_in_ms, bool *timed_out_ptr)

CDI_INTERFACE bool	CdiOsSignalsWait (CdiSignalType signal_array, uint8_t num_signals, bool wait_all, uint32_t timeout_in_ms, uint32_t ret_signal_index_ptr)

CDI_INTERFACE void *	CdiOsMemAlloc (int64_t mem_size)

CDI_INTERFACE void *	CdiOsMemAllocZero (int64_t mem_size)

CDI_INTERFACE void	CdiOsMemFree (void *mem_ptr)

CDI_INTERFACE void *	CdiOsMemAllocHugePage (int64_t mem_size)

CDI_INTERFACE void	CdiOsMemFreeHugePage (void *mem_ptr, int64_t mem_size)

CDI_INTERFACE bool	CdiOsOpenForWrite (const char file_name_str, CdiFileID file_handle_ptr)

CDI_INTERFACE bool	CdiOsOpenForRead (const char file_name_str, CdiFileID file_handle_ptr)

CDI_INTERFACE bool	CdiOsClose (CdiFileID file_handle)

CDI_INTERFACE bool	CdiOsRead (CdiFileID file_handle, void buffer_ptr, uint32_t byte_count, uint32_t bytes_read_ptr)

CDI_INTERFACE bool	CdiOsWrite (CdiFileID file_handle, const void *data_ptr, uint32_t byte_count)

CDI_INTERFACE bool	CdiOsFlush (CdiFileID file_handle)

CDI_INTERFACE bool	CdiOsFTell (CdiFileID file_handle, uint64_t *current_position_ptr)

CDI_INTERFACE bool	CdiOsFSeek (CdiFileID file_handle, int64_t offset, int position)

CDI_INTERFACE bool	CdiOsSplitPath (const char filepath_str, char filename_str, int filename_buf_size, char *directory_str, int directory_buf_size)

CDI_INTERFACE bool	CdiOsIsPathWriteable (const char *directory_str)

CDI_INTERFACE int	CdiOsStrCpy (char dest_str, uint32_t max_str_len, const char src_str)

CDI_INTERFACE void	CdiOsSleep (uint32_t milliseconds)

CDI_INTERFACE void	CdiOsSleepMicroseconds (uint32_t microseconds)

CDI_INTERFACE uint64_t	CdiOsGetMicroseconds (void)
	Timers get a microsecond timestamp from CLOCK_MONOTONIC on linux or from the performance counter on Windows.

CDI_INTERFACE void	CdiOsGetUtcTime (struct timespec *ret_time_ptr)
	This is an OS call to get the current synced AWS network time in UTC format.

CDI_INTERFACE void	CdiOsGetLocalTime (struct tm *local_time_ret_ptr)

CDI_INTERFACE int	CdiOsGetLocalTimeString (char *time_str, int max_string_len)

CDI_INTERFACE bool	CdiOsSocketOpen (const char host_address_str, int port_number, const char bind_address_str, CdiSocket *new_socket_ptr)

CDI_INTERFACE bool	CdiOsSocketGetPort (CdiSocket socket_handle, int *port_number_ptr)

CDI_INTERFACE bool	CdiOsSocketGetSockAddrIn (CdiSocket socket_handle, struct sockaddr_in *sockaddr_in_ptr)

CDI_INTERFACE bool	CdiOsSocketClose (CdiSocket socket_handle)

CDI_INTERFACE bool	CdiOsSocketRead (CdiSocket socket_handle, void buffer_ptr, int byte_count_ptr)

CDI_INTERFACE bool	CdiOsSocketReadFrom (CdiSocket socket_handle, void buffer_ptr, int byte_count_ptr, struct sockaddr_in *source_address_ptr)

CDI_INTERFACE bool	CdiOsSocketWrite (CdiSocket socket_handle, struct iovec iov, int iovcnt, int byte_count_ptr)

CDI_INTERFACE bool	CdiOsSocketWriteTo (CdiSocket socket_handle, struct iovec iov, int iovcnt, const struct sockaddr_in destination_address_ptr, int *byte_count_ptr)

CDI_INTERFACE bool	CdiOsEnvironmentVariableSet (const char name_str, const char value_str)

CDI_INTERFACE void	CdiOsShutdown (void)

Detailed Description

This file contains the declarations for OS functions for creating/managing/freeing threads, semaphores, mutexes, critical sections, signals, memory and sockets. There are also abstractions for atomic operations as well as some time, sleep and string operations. These definitions in this module are here to account for differences between Linux and Windows.

Macro Definition Documentation

◆ CdiOsAtomicLoad16

#define CdiOsAtomicLoad16 ( x ) __atomic_load_n((x), __ATOMIC_CONSUME)

Atomic load value. Valid memory models are:

__ATOMIC_RELAXED : No barriers or synchronization.
__ATOMIC_CONSUME : Data dependency only for both barrier and synchronization with another thread.
__ATOMIC_ACQUIRE : Barrier to hoisting of code and synchronizes with release (or stronger) semantic stores from
                   another thread.
__ATOMIC_SEQ_CST : Full barrier in both directions and synchronizes with acquire loads and release stores in
                   all threads.

◆ CdiOsAtomicStore16

#define CdiOsAtomicStore16	(		x,
			v ) __atomic_store_n((x), (v), __ATOMIC_RELEASE)

Atomic store value. Valid memory models are:

__ATOMIC_RELAXED : No barriers or synchronization.
__ATOMIC_RELEASE : Barrier to sinking of code and synchronizes with acquire (or stronger) semantic loads from
                   another thread.
__ATOMIC_SEQ_CST : Full barrier in both directions and synchronizes with acquire loads and release stores in
                   all threads.

◆ CdiOsGetMilliseconds

#define CdiOsGetMilliseconds ( ) (CdiOsGetMicroseconds()/1000)

Macro to get OS time in milliseconds that uses CdiOsGetMicroseconds().

Returns: Millisecond timestamp.

◆ CdiOsStrCmp

#define CdiOsStrCmp strcmp

Used to compare two strings.

Parameters

string1	C string to be compared with string2.
string2	C string to be compared with string1.
num	Maximum number of characters to compare. NOTE: num is size_t.

Returns: Returns int = 0 both substrings are identical, <0 string1 first non-matching character has a lower value than string2, >0 string1 first non-matching character has a higher value than string2.

◆ CdiOsStrNCmp

#define CdiOsStrNCmp strncmp

Used to compare two strings specifying the number of characters to compare.

Parameters

string1	C string to be compared with string2.
string2	C string to be compared with string1.
num	Maximum number of characters to compare. NOTE: num is size_t.

Returns: Returns int =0 both substrings are identical, <0 string1 first non-matching character has a lower value than string2, >0 string1 first non-matching character has a higher value than string2.

Typedef Documentation

◆ CdiStaticMutexType

typedef pthread_mutex_t CdiStaticMutexType

Define portable static mutex type. An example implementation:

static CdiStaticMutexType my_lock = CDI_STATIC_MUTEX_INITIALIZER;
 
void Foo() {
    CdiOsStaticMutexLock(my_lock);
    // Do something that uses a shared resource.
    CdiOsStaticMutexLock(my_lock);
}

Function Documentation

◆ CdiOsClose()

CDI_INTERFACE bool CdiOsClose ( CdiFileID file_handle )

Closes a file.

Parameters

file_handle Identifier of file to close.

Returns: true if successful, otherwise false.

◆ CdiOsCritSectionCreate()

CDI_INTERFACE bool CdiOsCritSectionCreate ( CdiCsID * cs_handle_ptr )

Creates and initializes a critical section.

Parameters

cs_handle_ptr Pointer to critical section ID to return.

Returns: true if successful, otherwise false.

◆ CdiOsCritSectionDelete()

CDI_INTERFACE bool CdiOsCritSectionDelete ( CdiCsID cs_handle )

Deletes a critical section.

Parameters

cs_handle Pointer to critical section ID to delete.

Returns: true if successful, otherwise false.

◆ CdiOsCritSectionRelease()

CDI_INTERFACE void CdiOsCritSectionRelease ( CdiCsID cs_handle )

Releases the specified critical section.

Parameters

cs_handle Critical section ID to release.

◆ CdiOsCritSectionReserve()

CDI_INTERFACE void CdiOsCritSectionReserve ( CdiCsID cs_handle )

Reserves the specified critical section.

Parameters

cs_handle Critical section ID to reserve.

◆ CdiOsEnvironmentVariableSet()

CDI_INTERFACE bool CdiOsEnvironmentVariableSet	(	const char *	name_str,
		const char *	value_str )

Set an environment variable for the currently running process. NOTE: Does not set the process's shell environment.

Parameters

name_str	Pointer to string name of variable to set. Assumed to be a non-NULL value.
value_str	Pointer to string value to set. NOTE: Cannot be NULL.

Returns: true if successful, otherwise false.

◆ CdiOsFlush()

CDI_INTERFACE bool CdiOsFlush ( CdiFileID file_handle )

Flushes write buffers for the specified file.

Parameters

file_handle Identifier of the file to flush.

Returns: true if successful, otherwise false.

◆ CdiOsFSeek()

CDI_INTERFACE bool CdiOsFSeek	(	CdiFileID	file_handle,
		int64_t	offset,
		int	position )

Retrieves the current file position for the specified file.

Parameters

file_handle	Identifier of the file.
offset	Number of bytes to offset from position.
position	The position from where offset is added.

Returns: true if successful, otherwise false.

◆ CdiOsFTell()

CDI_INTERFACE bool CdiOsFTell	(	CdiFileID	file_handle,
		uint64_t *	current_position_ptr )

Retrieves the current file position for the specified file.

Parameters

file_handle	Identifier of the file.
current_position_ptr	Pointer to current position of the file.

Returns: true if successful, otherwise false.

◆ CdiOsGetLocalTime()

CDI_INTERFACE void CdiOsGetLocalTime ( struct tm * local_time_ret_ptr )

Get current local time as "tm" structure.

Parameters

local_time_ret_ptr Pointer to returned local time.

◆ CdiOsGetLocalTimeString()

CDI_INTERFACE int CdiOsGetLocalTimeString	(	char *	time_str,
		int	max_string_len )

Get current local time as a formatted as ISO 8601.

Parameters

time_str	Formatted string to represent ISO 8601 time format.
max_string_len	Maximum allowable characters in the time string.

Returns: char_count Returns the number of characters of the formatted string.

◆ CdiOsGetMicroseconds()

CDI_INTERFACE uint64_t CdiOsGetMicroseconds ( void )

Timers get a microsecond timestamp from CLOCK_MONOTONIC on linux or from the performance counter on Windows.

Returns: Microsecond timestamp.

◆ CdiOsGetUtcTime()

CDI_INTERFACE void CdiOsGetUtcTime ( struct timespec * ret_time_ptr )

This is an OS call to get the current synced AWS network time in UTC format.

This function will be kept up to date with the best practices for getting high accuracy time from Amazon Time Sync Service as improved accuracy time is available. All EC2 instances that call this function should be using the Amazon Time Sync Service. Amazon Time Sync Service setup directions for Linux can be found at: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html#configure-amazon-time-service

For Windows follow the directions at: https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/windows-set-time.html

Parameters

ret_time_ptr a pointer returned to a UTC timestamp in the format of a timespec structure as defined by time.h.

◆ CdiOsIsPathWriteable()

CDI_INTERFACE bool CdiOsIsPathWriteable ( const char * directory_str )

Takes in a directory string and verifies that the directory exists and is writeable.

Parameters

directory_str String containing the directory path, including any end '/' without the filename.

Returns: true if successful, otherwise false.

◆ CdiOsMemAlloc()

CDI_INTERFACE void * CdiOsMemAlloc ( int64_t mem_size )

Allocates a block of memory and returns a pointer to the start of the block.

Parameters

mem_size Number of bytes to allocate.

Returns: Pointer to the allocated memory block. If unable to allocate the memory block, NULL is returned.

◆ CdiOsMemAllocHugePage()

CDI_INTERFACE void * CdiOsMemAllocHugePage ( int64_t mem_size )

Allocates a block of huge page memory and returns a pointer to the start of the block.

Parameters

mem_size Number of bytes to allocate. Size must be a multiple of CDI_HUGE_PAGES_BYTE_SIZE. If not, NULL is returned.

Returns: Pointer to the allocated memory block. If unable to allocate the memory block, NULL is returned.

◆ CdiOsMemAllocZero()

CDI_INTERFACE void * CdiOsMemAllocZero ( int64_t mem_size )

Allocates a block of memory, writes zero across its entirety, and returns a pointer to the start of the block.

Parameters

mem_size Number of bytes to allocate.

Returns: Pointer to the allocated memory block. If unable to allocate the memory block, NULL is returned.

◆ CdiOsMemFree()

CDI_INTERFACE void CdiOsMemFree ( void * mem_ptr )

Releases a previously allocated block of memory.

Parameters

mem_ptr Pointer to start address of memory block.

◆ CdiOsMemFreeHugePage()

CDI_INTERFACE void CdiOsMemFreeHugePage	(	void *	mem_ptr,
		int64_t	mem_size )

Releases a previously allocated block of huge page memory.

Parameters

mem_ptr	Pointer to start address of memory block.
mem_size	Number of bytes that were allocated.

◆ CdiOsOpenForRead()

CDI_INTERFACE bool CdiOsOpenForRead	(	const char *	file_name_str,
		CdiFileID *	file_handle_ptr )

Opens a file (file_name_str) for read and returns a file handle.

Parameters

file_name_str	Pointer to filename to open.
file_handle_ptr	Address where to write returned file handle.

Returns: true if successful, otherwise false.

◆ CdiOsOpenForWrite()

CDI_INTERFACE bool CdiOsOpenForWrite	(	const char *	file_name_str,
		CdiFileID *	file_handle_ptr )

Opens a file (file_name_str) for writing and returns a file handle.

Parameters

file_name_str	Pointer to filename to open.
file_handle_ptr	Address where to write returned file handle.

Returns: true if successful, otherwise false.

◆ CdiOsRead()

CDI_INTERFACE bool CdiOsRead	(	CdiFileID	file_handle,
		void *	buffer_ptr,
		uint32_t	byte_count,
		uint32_t *	bytes_read_ptr )

Reads data from a file.

Parameters

file_handle	Identifier of file to read from.
buffer_ptr	Pointer to buffer to read in to.
byte_count	Number of bytes to read into the buffer pointed to by buffer_ptr.
bytes_read_ptr	Returns the number of bytes read (NULL if you don't care).

Returns: true if successful, otherwise false. Check EOF using OS's EOF API function.

◆ CdiOsSemaphoreCreate()

CDI_INTERFACE bool CdiOsSemaphoreCreate	(	CdiSemID *	ret_sem_handle_ptr,
		int	sem_count )

Creates a semaphore.

Parameters

ret_sem_handle_ptr	Pointer to semaphore ID to return.
sem_count	Initial semaphore count.

Returns: true if successful, otherwise false.

◆ CdiOsSemaphoreDelete()

CDI_INTERFACE bool CdiOsSemaphoreDelete ( CdiSemID sem_handle )

Deletes a semaphore.

Parameters

sem_handle Pointer to semaphore ID to delete.

Returns: returns true if successful, otherwise false is returned.

◆ CdiOsSemaphoreRelease()

CDI_INTERFACE bool CdiOsSemaphoreRelease ( CdiSemID sem_handle )

Releases a semaphore.

Parameters

sem_handle Semaphore ID to release.

Returns: true if successful, otherwise false.

◆ CdiOsSemaphoreReserve()

CDI_INTERFACE bool CdiOsSemaphoreReserve	(	CdiSemID	sem_handle,
		int	timeout_in_ms )

Reserves a semaphore and blocks if the current semaphore count is 0. If the semaphore is already reserved by the calling thread, then this call simply returns success.

Parameters

sem_handle	Semaphore ID to reserve.
timeout_in_ms	Amount of miliseconds to wait for the semaphore, CDI_INFINITE to wait indefinitely.

Returns: true if successful, otherwise false.

◆ CdiOsSemaphoreValueGet()

CDI_INTERFACE int CdiOsSemaphoreValueGet ( CdiSemID sem_handle )

Returns the value of the given semaphore (ie. how many semaphore resources are available).

Parameters

sem_handle Semaphore ID to check.

Returns: Value of semaphore.

◆ CdiOsShutdown()

CDI_INTERFACE void CdiOsShutdown ( void )

Shuts down OS specific resources used by the SDK.

◆ CdiOsSignalClear()

CDI_INTERFACE bool CdiOsSignalClear ( CdiSignalType signal_handle )

This function clears a signal.

Parameters

signal_handle A signal handle to clear the value of.

Returns: true if successful, otherwise false.

◆ CdiOsSignalCreate()

CDI_INTERFACE bool CdiOsSignalCreate ( CdiSignalType * signal_handle_ptr )

This function creates a signal. The initial value is not signaled.

Parameters

signal_handle_ptr Address where to write the returned signal handle.

Returns: true if successful, otherwise false.

◆ CdiOsSignalDelete()

CDI_INTERFACE bool CdiOsSignalDelete ( CdiSignalType signal_handle )

This function deletes a signal.

Parameters

signal_handle A signal handle to delete.

Returns: true if successful, otherwise false.

◆ CdiOsSignalGet()

CDI_INTERFACE bool CdiOsSignalGet ( CdiSignalType signal_handle )

This function returns the value of the signal passed in.

Parameters

signal_handle A signal handle to get the value of.

Returns: true if successful, otherwise false.

◆ CdiOsSignalHandlerSet()

CDI_INTERFACE bool CdiOsSignalHandlerSet	(	int	signal_num,
		CdiSignalHandlerFunction	func_ptr )

Set the address to the default signal handler function shared by all threads.

Parameters

signal_num	Number of the signal to set the new handler.
func_ptr	Address of signal handler function to set for the signal.

Returns: true on success, false if there isn't enough storage to hold the signal or if there was an error.

◆ CdiOsSignalReadState()

CDI_INTERFACE bool CdiOsSignalReadState ( CdiSignalType signal_handle )

This function returns the value of the signal passed in without using any OS resources. It only accesses state data.

Parameters

signal_handle A signal handle to read the state value of.

Returns: true if successful, otherwise false.

◆ CdiOsSignalSet()

CDI_INTERFACE bool CdiOsSignalSet ( CdiSignalType signal_handle )

This function sets a signal and its related state variable.

Parameters

signal_handle A signal handle to set the value of.

Returns: true if successful, otherwise false.

◆ CdiOsSignalsWait()

CDI_INTERFACE bool CdiOsSignalsWait	(	CdiSignalType *	signal_array,
		uint8_t	num_signals,
		bool	wait_all,
		uint32_t	timeout_in_ms,
		uint32_t *	ret_signal_index_ptr )

This function waits for an array of signals.

Parameters

signal_array	Pointer to an array of signal handles to wait on.
num_signals	Number of signals in the array.
wait_all	Use true to wait for all signals, false to block on any signal.
timeout_in_ms	Timeout in mSec can be CDI_INFINITE to wait indefinitely.
ret_signal_index_ptr	Pointer to the returned signal index that caused the thread to be signaled. if wait_all is true, then this is set to 1 when all signals are signaled. If a timeout occurred, CDI_OS_SIG_TIMEOUT is returned. This is an optional parameter, you can pass NULL if you don't care.

Returns: true if successful, otherwise false.

◆ CdiOsSignalWait()

CDI_INTERFACE bool CdiOsSignalWait	(	CdiSignalType	signal_handle,
		uint32_t	timeout_in_ms,
		bool *	timed_out_ptr )

This function waits for a signal.

Parameters

signal_handle	A signal handle to wait on.
timeout_in_ms	Timeout in mSec can be CDI_INFINITE to wait indefinitely.
timed_out_ptr	Pointer to boolean - set to true if timed out.

Returns: true if successful, otherwise false.

◆ CdiOsSleep()

CDI_INTERFACE void CdiOsSleep ( uint32_t milliseconds )

Block the current thread for the specified number of milliseconds.

Parameters

milliseconds Block thread for this much time.

◆ CdiOsSleepMicroseconds()

CDI_INTERFACE void CdiOsSleepMicroseconds ( uint32_t microseconds )

Block the current thread for microseconds.

Parameters

microseconds Block thread for this much time.

◆ CdiOsSocketClose()

CDI_INTERFACE bool CdiOsSocketClose ( CdiSocket socket_handle )

Close a previously opened communications socket, freeing resources that were allocated for it including the local port if the socket was opened for receiving.

Parameters

socket_handle The handle of the socket which is to be closed.

Returns: true if the socket was closed cleanly, false if a problem was encountered trying to close it.

◆ CdiOsSocketGetPort()

CDI_INTERFACE bool CdiOsSocketGetPort	(	CdiSocket	socket_handle,
		int *	port_number_ptr )

Gets the number of the port to which the specified socket is bound. This is useful for receive sockets opened with their port number specified as 0, which makes the operating system assign a random port number. It also works on transmit sockets which are also randomly assigned a port number.

Parameters

socket_handle	The socket whose port number is of interest.
port_number_ptr	Address of where the port number will be written.

Returns: true if the port number could be determined or false if a problem was encountered.

◆ CdiOsSocketGetSockAddrIn()

CDI_INTERFACE bool CdiOsSocketGetSockAddrIn	(	CdiSocket	socket_handle,
		struct sockaddr_in *	sockaddr_in_ptr )

Gets the sockaddr_in structure to which the specified socket is bound.

Parameters

socket_handle	The socket whose port number is of interest.
sockaddr_in_ptr	Address of where the sockaddr_in data will be written.

Returns: true if the sockaddr_in data could be determined or false if a problem was encountered.

◆ CdiOsSocketOpen()

CDI_INTERFACE bool CdiOsSocketOpen	(	const char *	host_address_str,
		int	port_number,
		const char *	bind_address_str,
		CdiSocket *	new_socket_ptr )

Opens a unidirectional or bidirectional Internet Protocol User Datagram Protocol (IP/UDP) socket for communications. For a unidirectional socket to send on, specify the host address of the remote host. To create a unidirectional socket for receiving, specify NULL as host_address_str.

For a bidirectional socket, where datagrams can be sent and received through the socket, specify NULL as host_address_str for both client and server sides. For the client side, specify zero for port_number so a randomly selected port number is used. Call

See also: CdiOsSocketGetPort to determine the port number that was assigned. When sending datagrams, Use; CdiOsSocketWriteTo to specify the remote destination address and port. For the server side, specify the local port number for port_number to listen for incoming datagrams. Use; CdiOsSocketReadFrom so that the datagram's source host's IP address and port number are provided.

Parameters

host_address_str	The address of the remote host (dotted IPv4 address) to which to send datagrams or NULL if the socket is to be used for receiving datagrams or is bidirectional.
port_number	For a unidirectional send-only socket, the numeric port number on the remote host. For a unidirectional receive only socket or server side of a bidirectional socket, the local port number to listen for incoming datagrams. For the client side of a bidirectional socket, use zero for this value so that a randomly selected port number is used. Call

See also: CdiOsSocketGetPort to determine the port number that was assigned.

Parameters

bind_address_str	Optional bind address (dotted IPv4 address). If NULL, default interface is used.
new_socket_ptr	A pointer to the location which will get the new socket handle written to it.

Returns: true if the socket was successfully opened and is ready for communications, otherwise false.

◆ CdiOsSocketRead()

CDI_INTERFACE bool CdiOsSocketRead	(	CdiSocket	socket_handle,
		void *	buffer_ptr,
		int *	byte_count_ptr )

Synchronously reads the next available datagram from the specified socket. If no datagram is available after a short timeout, true is returned but the value written to byte_count_ptr will be zero. This timeout is so that the caller can periodically check whether to shut down its polling loop.

Parameters

socket_handle	The handle for the socket for which incoming datagrams are to be received.
buffer_ptr	The address in memory where the bytes of the datagram will be written.
byte_count_ptr	On entry, the value at the location pointed to must be the size of the buffer at buffer_ptr available for the datagram to be written. At exit, the address will be overwritten with the number of bytes that are actually contained in the datagram and thus written to the buffer. A value of 0 indicates that the read timed out waiting for a datagram and that the read should be retried unless the polling process should be shut down.

Returns: true if the function succeeded, false if it failed. Timing out is considered to be success but zero will have been written to byte_count_ptr to disambiguate a timeout condition from data being written into the buffer.

◆ CdiOsSocketReadFrom()

CDI_INTERFACE bool CdiOsSocketReadFrom	(	CdiSocket	socket_handle,
		void *	buffer_ptr,
		int *	byte_count_ptr,
		struct sockaddr_in *	source_address_ptr )

Synchronously reads the next available datagram from the specified socket and provides the source IP address/port number. If no datagram is available after a short timeout, true is returned but the value written to byte_count_ptr will be zero. This timeout is so that the caller can periodically check whether to shut down its polling loop.

Parameters

socket_handle	The handle for the socket for which incoming datagrams are to be received.
buffer_ptr	The address in memory where the bytes of the datagram will be written.
byte_count_ptr	On entry, the value at the location pointed to must be the size of the buffer at buffer_ptr available for the datagram to be written. At exit, the address will be overwritten with the number of bytes that are actually contained in the datagram and thus written to the buffer. A value of 0 indicates that the read timed out waiting for a datagram and that the read should be retried unless the polling process should be shut down.
source_address_ptr	Pointer to memory where the source address and port number from the UDP packet will be written so that the caller can determine where to send replies.

Returns: true if the function succeeded, false if it failed. Timing out is considered to be success but zero will have been written to byte_count_ptr to disambiguate a timeout condition from data being written into the buffer.

◆ CdiOsSocketWrite()

CDI_INTERFACE bool CdiOsSocketWrite	(	CdiSocket	socket_handle,
		struct iovec *	iov,
		int	iovcnt,
		int *	byte_count_ptr )

Synchronously write a datagram to a communications socket. The data is represented as an array of address pointers and sizes. This data is copied inside of the function so once it returns the buffer(s) are available for reuse.

Parameters

socket_handle	The handle for the socket through which the datagram will be written.
iov	The address of an array of iovec structures which specify the data to be sent.
iovcnt	The number of iovec structures contained in the iov array. This value is limited to CDI_OS_SOCKET_MAX_IOVCNT.
byte_count_ptr	The address of a location into which the number of bytes written to the socket will be placed if the datagram was successfully sent.

Returns: true if the datagram was successfully sent, false if not. Note that there is no guarantee that the datagram was actually received by the destination host.

◆ CdiOsSocketWriteTo()

CDI_INTERFACE bool CdiOsSocketWriteTo	(	CdiSocket	socket_handle,
		struct iovec *	iov,
		int	iovcnt,
		const struct sockaddr_in *	destination_address_ptr,
		int *	byte_count_ptr )

Synchronously write a datagram to a communications socket. The data is represented as an array of address pointers and sizes. This data is copied inside of the function so once it returns the buffer(s) are available for reuse.

Parameters

socket_handle	The handle for the socket through which the datagram will be written.
iov	The address of an array of iovec structures which specify the data to be sent.
iovcnt	The number of iovec structures contained in the iov array. This value is limited to RMT_OS_SOCKET_MAX_IOVCNT.
destination_address_ptr	Pointer to the destination (IP address and port number) to which to send the UDP packet.
byte_count_ptr	The address of a location into which the number of bytes written to the socket will be placed if the datagram was successfully sent.

Returns: true if the datagram was successfully sent, false if not. Note that there is no guarantee that the datagram was actually received by the destination host.

◆ CdiOsSplitPath()

CDI_INTERFACE bool CdiOsSplitPath	(	const char *	filepath_str,
		char *	filename_str,
		int	filename_buf_size,
		char *	directory_str,
		int	directory_buf_size )

Takes in a filepath and breaks it into its component directory and filename.

Parameters

filepath_str	String containing a path name and filename.
filename_str	String containing the filename without the path. Pass NULL for this parameter if the filename is not needed.
filename_buf_size	Size of the buffer sent for storing the filename string.
directory_str	String containing the directory path, including any end '/' without the filename. Pass NULL for this parameter if the directory path is not needed.
directory_buf_size	Size of the buffer sent for storing the directory path string.

Returns: true if successful, otherwise false.

◆ CdiOsStrCpy()

CDI_INTERFACE int CdiOsStrCpy	(	char *	dest_str,
		uint32_t	max_str_len,
		const char *	src_str )

A portable version of strcpy with range checking to replace Microsoft's strcpy_s.

Parameters

dest_str	Buffer to receive copied string.
max_str_len	Maximum number of characters to copy. This includes the terminating '\0'.
src_str	Source string to copy.

Returns: Number of characters copied.

◆ CdiOsThreadAllocData()

CDI_INTERFACE bool CdiOsThreadAllocData ( CdiThreadData * handle_out_ptr )

Allocates a slot of thread-local storage. The slot is allocated once for the whole program, after which each thread can store and read private data from the slot.

Parameters

handle_out_ptr Returned handle for a thread data slot.

Returns: true if successful, otherwise false.

◆ CdiOsThreadCreate()

static bool CdiOsThreadCreate	(	CdiThreadFuncName	thread_func,
		CdiThreadID *	thread_id_out_ptr,
		const char *	thread_name_str,
		void *	thread_func_arg_ptr,
		CdiSignalType	start_signal )

inlinestatic

Creates a thread. Note that thread pinning is inherited, so the launched thread will inherit the affinity of its parent if not explicitly set.

Parameters

thread_func	Pointer to a function for the thread.
thread_id_out_ptr	Pointer to CdiThreadID to return.
thread_name_str	Optional Thread Name for debugging and logging purposes (NULL if don't care).
thread_func_arg_ptr	Optional pointer to user data passed to the thread delegate.
start_signal	Optional signal used to start the thread. If NULL, thread starts running immediately.

Returns: true if successful, otherwise false.

◆ CdiOsThreadCreatePinned()

CDI_INTERFACE bool CdiOsThreadCreatePinned	(	CdiThreadFuncName	thread_func,
		CdiThreadID *	thread_id_out_ptr,
		const char *	thread_name_str,
		void *	thread_func_arg_ptr,
		CdiSignalType	start_signal,
		int	cpu_affinity )

Creates a thread which can optionally be pinned to a specific CPU.

Parameters

thread_func	Pointer to a function for the thread.
thread_id_out_ptr	Pointer to CdiThreadID to return.
thread_name_str	Optional Thread Name for debugging and logging purposes (NULL if don't care).
thread_func_arg_ptr	Optional pointer to user data passed to the thread delegate.
start_signal	Optional signal used to start the thread. If NULL, thread starts running immediately.
cpu_affinity	Zero-based CPU number to pin this thread to, -1 to not pin.

Returns: true if successful, otherwise false.

◆ CdiOsThreadFreeData()

CDI_INTERFACE bool CdiOsThreadFreeData ( CdiThreadData handle )

Frees a slot of thread-local storage. Should be called before program exit but after all threads are done using the slot.

Parameters

handle Handle of thread data to free.

Returns: true if successful, otherwise false.

◆ CdiOsThreadGetData()

CDI_INTERFACE bool CdiOsThreadGetData	(	CdiThreadData	handle,
		void **	content_out_ptr )

Get the value of this thread's copy of a thread-local storage slot.

Parameters

handle	Handle to thread data slot.
content_out_ptr	Pointer to a variable which receives the data.

Returns: true if successful, otherwise false.

◆ CdiOsThreadGetName()

CDI_INTERFACE const char * CdiOsThreadGetName ( CdiThreadID thread_id )

Get the name of the thread that was created using CdiOsThreadCreatePinned().

Parameters

thread_id Data structure for thread to get name.

Returns: Pointer to name of the thread.

◆ CdiOsThreadJoin()

CDI_INTERFACE bool CdiOsThreadJoin	(	CdiThreadID	thread_id,
		uint32_t	timeout_in_ms,
		bool *	timed_out_ptr )

Waits/blocks until the given thread has finished.

Parameters

thread_id	Data structure for thread to wait for.
timeout_in_ms	How long to wait for join before timing out.
timed_out_ptr	Pointer to a boolean that indicates a timeout has occurred when true.

Returns: true if successful, otherwise false.

◆ CdiOsThreadSetData()

CDI_INTERFACE bool CdiOsThreadSetData	(	CdiThreadData	handle,
		void *	content_ptr )

Stores a value in this thread's copy of a thread-local storage slot. Calls to osThreadGetData from the same thread will get this value back. The slot must have been allocated by CdiOsThreadAllocData.

Parameters

handle	Handle to thread data slot.
content_ptr	Pointer to be stored in the slot.

Returns: true if successful, otherwise false.

◆ CdiOsUseLogger()

CDI_INTERFACE void CdiOsUseLogger ( void )

Enable use of the logger when generating error messages. This function is normally used internally as part of initialization of the CDI SDK. If it is not used, then output will be directed to stderr.

◆ CdiOsWrite()

CDI_INTERFACE bool CdiOsWrite	(	CdiFileID	file_handle,
		const void *	data_ptr,
		uint32_t	byte_count )

Writes a file.

Parameters

file_handle	Identifier of file to write to.
data_ptr	Pointer to data to write.
byte_count	Number of bytes to write.

Returns: true if successful, otherwise false.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ CdiOsAtomicLoad16

◆ CdiOsAtomicStore16

◆ CdiOsGetMilliseconds

◆ CdiOsStrCmp

◆ CdiOsStrNCmp

Typedef Documentation

◆ CdiStaticMutexType

Function Documentation

◆ CdiOsClose()

◆ CdiOsCritSectionCreate()

◆ CdiOsCritSectionDelete()

◆ CdiOsCritSectionRelease()

◆ CdiOsCritSectionReserve()

◆ CdiOsEnvironmentVariableSet()

◆ CdiOsFlush()

◆ CdiOsFSeek()

◆ CdiOsFTell()

◆ CdiOsGetLocalTime()

◆ CdiOsGetLocalTimeString()

◆ CdiOsGetMicroseconds()

◆ CdiOsGetUtcTime()

◆ CdiOsIsPathWriteable()

◆ CdiOsMemAlloc()

◆ CdiOsMemAllocHugePage()

◆ CdiOsMemAllocZero()

◆ CdiOsMemFree()

◆ CdiOsMemFreeHugePage()

◆ CdiOsOpenForRead()

◆ CdiOsOpenForWrite()

◆ CdiOsRead()

◆ CdiOsSemaphoreCreate()

◆ CdiOsSemaphoreDelete()

◆ CdiOsSemaphoreRelease()

◆ CdiOsSemaphoreReserve()

◆ CdiOsSemaphoreValueGet()

◆ CdiOsShutdown()

◆ CdiOsSignalClear()

◆ CdiOsSignalCreate()

◆ CdiOsSignalDelete()

◆ CdiOsSignalGet()

◆ CdiOsSignalHandlerSet()

◆ CdiOsSignalReadState()

◆ CdiOsSignalSet()

◆ CdiOsSignalsWait()

◆ CdiOsSignalWait()

◆ CdiOsSleep()

◆ CdiOsSleepMicroseconds()

◆ CdiOsSocketClose()

◆ CdiOsSocketGetPort()

◆ CdiOsSocketGetSockAddrIn()

◆ CdiOsSocketOpen()

◆ CdiOsSocketRead()

◆ CdiOsSocketReadFrom()

◆ CdiOsSocketWrite()

◆ CdiOsSocketWriteTo()

◆ CdiOsSplitPath()

◆ CdiOsStrCpy()

◆ CdiOsThreadAllocData()

◆ CdiOsThreadCreate()

◆ CdiOsThreadCreatePinned()

◆ CdiOsThreadFreeData()

◆ CdiOsThreadGetData()

◆ CdiOsThreadGetName()

◆ CdiOsThreadJoin()

◆ CdiOsThreadSetData()

◆ CdiOsUseLogger()

◆ CdiOsWrite()