OS API

Interface for providing OS-specific functionality. More...

Collaboration diagram for OS API:

Classes
struct	ecs_time_t
	Time type. More...
struct	ecs_os_api_t
	OS API interface. More...

Macros
#define	ecs_os_perf_trace_push(name)
#define	ecs_os_perf_trace_pop(name)

Typedefs
typedef struct ecs_time_t	ecs_time_t
	Time type.
typedef uintptr_t	ecs_os_thread_t
	Use handle types that at least can store pointers.
typedef uintptr_t	ecs_os_cond_t
	OS cond.
typedef uintptr_t	ecs_os_mutex_t
	OS mutex.
typedef uintptr_t	ecs_os_dl_t
	OS dynamic library.
typedef uintptr_t	ecs_os_sock_t
	OS socket.
typedef uint64_t	ecs_os_thread_id_t
	64-bit thread ID.
typedef void(*	ecs_os_proc_t) (void)
	Generic function pointer type.
typedef void(*	ecs_os_api_init_t) (void)
	OS API init.
typedef void(*	ecs_os_api_fini_t) (void)
	OS API deinit.
typedef void *(*	ecs_os_api_malloc_t) (ecs_size_t size)
	OS API malloc function type.
typedef void(*	ecs_os_api_free_t) (void *ptr)
	OS API free function type.
typedef void *(*	ecs_os_api_realloc_t) (void *ptr, ecs_size_t size)
	OS API realloc function type.
typedef void *(*	ecs_os_api_calloc_t) (ecs_size_t size)
	OS API calloc function type.
typedef char *(*	ecs_os_api_strdup_t) (const char *str)
	OS API strdup function type.
typedef void *(*	ecs_os_thread_callback_t) (void *)
	OS API thread_callback function type.
typedef ecs_os_thread_t(*	ecs_os_api_thread_new_t) (ecs_os_thread_callback_t callback, void *param)
	OS API thread_new function type.
typedef void *(*	ecs_os_api_thread_join_t) (ecs_os_thread_t thread)
	OS API thread_join function type.
typedef ecs_os_thread_id_t(*	ecs_os_api_thread_self_t) (void)
	OS API thread_self function type.
typedef ecs_os_thread_t(*	ecs_os_api_task_new_t) (ecs_os_thread_callback_t callback, void *param)
	OS API task_new function type.
typedef void *(*	ecs_os_api_task_join_t) (ecs_os_thread_t thread)
	OS API task_join function type.
typedef int32_t(*	ecs_os_api_ainc_t) (int32_t *value)
	Atomic increment and decrement.
typedef int64_t(*	ecs_os_api_lainc_t) (int64_t *value)
	OS API lainc function type.
typedef ecs_os_mutex_t(*	ecs_os_api_mutex_new_t) (void)
	Mutex.
typedef void(*	ecs_os_api_mutex_lock_t) (ecs_os_mutex_t mutex)
	OS API mutex_lock function type.
typedef void(*	ecs_os_api_mutex_unlock_t) (ecs_os_mutex_t mutex)
	OS API mutex_unlock function type.
typedef void(*	ecs_os_api_mutex_free_t) (ecs_os_mutex_t mutex)
	OS API mutex_free function type.
typedef ecs_os_cond_t(*	ecs_os_api_cond_new_t) (void)
	Condition variable.
typedef void(*	ecs_os_api_cond_free_t) (ecs_os_cond_t cond)
	OS API cond_free function type.
typedef void(*	ecs_os_api_cond_signal_t) (ecs_os_cond_t cond)
	OS API cond_signal function type.
typedef void(*	ecs_os_api_cond_broadcast_t) (ecs_os_cond_t cond)
	OS API cond_broadcast function type.
typedef void(*	ecs_os_api_cond_wait_t) (ecs_os_cond_t cond, ecs_os_mutex_t mutex)
	OS API cond_wait function type.
typedef void(*	ecs_os_api_sleep_t) (int32_t sec, int32_t nanosec)
	OS API sleep function type.
typedef void(*	ecs_os_api_enable_high_timer_resolution_t) (bool enable)
	OS API enable_high_timer_resolution function type.
typedef void(*	ecs_os_api_get_time_t) (ecs_time_t *time_out)
	OS API get_time function type.
typedef uint64_t(*	ecs_os_api_now_t) (void)
	OS API now function type.
typedef void(*	ecs_os_api_log_t) (int32_t level, const char *file, int32_t line, const char *msg)
	OS API log function type.
typedef void(*	ecs_os_api_abort_t) (void)
	OS API abort function type.
typedef ecs_os_dl_t(*	ecs_os_api_dlopen_t) (const char *libname)
	OS API dlopen function type.
typedef ecs_os_proc_t(*	ecs_os_api_dlproc_t) (ecs_os_dl_t lib, const char *procname)
	OS API dlproc function type.
typedef void(*	ecs_os_api_dlclose_t) (ecs_os_dl_t lib)
	OS API dlclose function type.
typedef char *(*	ecs_os_api_module_to_path_t) (const char *module_id)
	OS API module_to_path function type.
typedef void(*	ecs_os_api_perf_trace_t) (const char *filename, size_t line, const char *name)
	OS API performance tracing function type.
typedef struct ecs_os_api_t	ecs_os_api_t
	OS API interface.

Functions
FLECS_API void	ecs_os_init (void)
	Initialize the OS API.
FLECS_API void	ecs_os_fini (void)
	Deinitialize the OS API.
FLECS_API void	ecs_os_set_api (ecs_os_api_t *os_api)
	Override the OS API.
FLECS_API ecs_os_api_t	ecs_os_get_api (void)
	Get the OS API.
FLECS_API void	ecs_os_set_api_defaults (void)
	Set default values for the OS API.
FLECS_API void	ecs_os_dbg (const char *file, int32_t line, const char *msg)
	Macro utilities.
FLECS_API void	ecs_os_trace (const char *file, int32_t line, const char *msg)
	Log at trace level.
FLECS_API void	ecs_os_warn (const char *file, int32_t line, const char *msg)
	Log at warning level.
FLECS_API void	ecs_os_err (const char *file, int32_t line, const char *msg)
	Log at error level.
FLECS_API void	ecs_os_fatal (const char *file, int32_t line, const char *msg)
	Log at fatal level.
FLECS_API const char *	ecs_os_strerror (int err)
	Convert errno to a string.
FLECS_API void	ecs_os_strset (char **str, const char *value)
	A utility for assigning strings.
void	ecs_os_perf_trace_push_ (const char *file, size_t line, const char *name)
	Push a performance trace region.
void	ecs_os_perf_trace_pop_ (const char *file, size_t line, const char *name)
	Pop a performance trace region.
FLECS_API void	ecs_sleepf (double t)
	Sleep with floating-point time.
FLECS_API double	ecs_time_measure (ecs_time_t *start)
	Measure time since the provided timestamp.
FLECS_API ecs_time_t	ecs_time_sub (ecs_time_t t1, ecs_time_t t2)
	Calculate the difference between two timestamps.
FLECS_API double	ecs_time_to_double (ecs_time_t t)
	Convert a time value to a double.
FLECS_API void *	ecs_os_memdup (const void *src, ecs_size_t size)
	Return newly allocated memory that contains a copy of src.
FLECS_API bool	ecs_os_has_heap (void)
	Are heap functions available?
FLECS_API bool	ecs_os_has_threading (void)
	Are threading functions available?
FLECS_API bool	ecs_os_has_task_support (void)
	Are task functions available?
FLECS_API bool	ecs_os_has_time (void)
	Are time functions available?
FLECS_API bool	ecs_os_has_logging (void)
	Are logging functions available?
FLECS_API bool	ecs_os_has_dl (void)
	Are dynamic library functions available?
FLECS_API bool	ecs_os_has_modules (void)
	Are module path functions available?

Variables
int64_t	ecs_os_api_malloc_count
	Allocation counters.
int64_t	ecs_os_api_realloc_count
	realloc count.
int64_t	ecs_os_api_calloc_count
	calloc count.
int64_t	ecs_os_api_free_count
	free count.
FLECS_API ecs_os_api_t	ecs_os_api
	Static OS API variable with configured callbacks.

Detailed Description

Interface for providing OS-specific functionality.

Macro Definition Documentation

ecs_os_perf_trace_pop

#define ecs_os_perf_trace_pop

(

name

)

Definition at line 667 of file os_api.h.

ecs_os_perf_trace_push

#define ecs_os_perf_trace_push

(

name

)

Definition at line 666 of file os_api.h.

Typedef Documentation

ecs_os_api_abort_t

typedef void(* ecs_os_api_abort_t) (void)

OS API abort function type.

Definition at line 229 of file os_api.h.

ecs_os_api_ainc_t

typedef int32_t(* ecs_os_api_ainc_t) (int32_t *value)

Atomic increment and decrement.

OS API ainc function type.

Definition at line 137 of file os_api.h.

ecs_os_api_calloc_t

typedef void *(* ecs_os_api_calloc_t) (ecs_size_t size)

OS API calloc function type.

Definition at line 95 of file os_api.h.

ecs_os_api_cond_broadcast_t

typedef void(* ecs_os_api_cond_broadcast_t) (ecs_os_cond_t cond)

OS API cond_broadcast function type.

Definition at line 184 of file os_api.h.

ecs_os_api_cond_free_t

typedef void(* ecs_os_api_cond_free_t) (ecs_os_cond_t cond)

OS API cond_free function type.

Definition at line 174 of file os_api.h.

ecs_os_api_cond_new_t

typedef ecs_os_cond_t(* ecs_os_api_cond_new_t) (void)

Condition variable.

OS API cond_new function type.

Definition at line 169 of file os_api.h.

ecs_os_api_cond_signal_t

typedef void(* ecs_os_api_cond_signal_t) (ecs_os_cond_t cond)

OS API cond_signal function type.

Definition at line 179 of file os_api.h.

ecs_os_api_cond_wait_t

typedef void(* ecs_os_api_cond_wait_t) (ecs_os_cond_t cond, ecs_os_mutex_t mutex)

OS API cond_wait function type.

Definition at line 189 of file os_api.h.

ecs_os_api_dlclose_t

typedef void(* ecs_os_api_dlclose_t) (ecs_os_dl_t lib)

OS API dlclose function type.

Definition at line 245 of file os_api.h.

ecs_os_api_dlopen_t

typedef ecs_os_dl_t(* ecs_os_api_dlopen_t) (const char *libname)

OS API dlopen function type.

Definition at line 234 of file os_api.h.

ecs_os_api_dlproc_t

typedef ecs_os_proc_t(* ecs_os_api_dlproc_t) (ecs_os_dl_t lib, const char *procname)

OS API dlproc function type.

Definition at line 239 of file os_api.h.

ecs_os_api_enable_high_timer_resolution_t

typedef void(* ecs_os_api_enable_high_timer_resolution_t) (bool enable)

OS API enable_high_timer_resolution function type.

Definition at line 201 of file os_api.h.

ecs_os_api_fini_t

typedef void(* ecs_os_api_fini_t) (void)

OS API deinit.

Definition at line 75 of file os_api.h.

ecs_os_api_free_t

typedef void(* ecs_os_api_free_t) (void *ptr)

OS API free function type.

Definition at line 84 of file os_api.h.

ecs_os_api_get_time_t

typedef void(* ecs_os_api_get_time_t) (ecs_time_t *time_out)

OS API get_time function type.

Definition at line 206 of file os_api.h.

ecs_os_api_init_t

typedef void(* ecs_os_api_init_t) (void)

OS API init.

Definition at line 71 of file os_api.h.

ecs_os_api_lainc_t

typedef int64_t(* ecs_os_api_lainc_t) (int64_t *value)

OS API lainc function type.

Definition at line 142 of file os_api.h.

ecs_os_api_log_t

typedef void(* ecs_os_api_log_t) (int32_t level, const char *file, int32_t line, const char *msg)

OS API log function type.

Parameters

level	The logging level.
file	The file where the message was logged.
line	The line where it was logged.
msg	The log message.

Definition at line 221 of file os_api.h.

ecs_os_api_malloc_t

typedef void *(* ecs_os_api_malloc_t) (ecs_size_t size)

OS API malloc function type.

Definition at line 79 of file os_api.h.

ecs_os_api_module_to_path_t

typedef char *(* ecs_os_api_module_to_path_t) (const char *module_id)

OS API module_to_path function type.

Definition at line 250 of file os_api.h.

ecs_os_api_mutex_free_t

typedef void(* ecs_os_api_mutex_free_t) (ecs_os_mutex_t mutex)

OS API mutex_free function type.

Definition at line 163 of file os_api.h.

ecs_os_api_mutex_lock_t

typedef void(* ecs_os_api_mutex_lock_t) (ecs_os_mutex_t mutex)

OS API mutex_lock function type.

Definition at line 153 of file os_api.h.

ecs_os_api_mutex_new_t

typedef ecs_os_mutex_t(* ecs_os_api_mutex_new_t) (void)

Mutex.

OS API mutex_new function type.

Definition at line 148 of file os_api.h.

ecs_os_api_mutex_unlock_t

typedef void(* ecs_os_api_mutex_unlock_t) (ecs_os_mutex_t mutex)

OS API mutex_unlock function type.

Definition at line 158 of file os_api.h.

ecs_os_api_now_t

typedef uint64_t(* ecs_os_api_now_t) (void)

OS API now function type.

Definition at line 211 of file os_api.h.

ecs_os_api_perf_trace_t

typedef void(* ecs_os_api_perf_trace_t) (const char *filename, size_t line, const char *name)

OS API performance tracing function type.

Parameters

filename	The source file name.
line	The source line number.
name	The name of the trace region.

Definition at line 259 of file os_api.h.

ecs_os_api_realloc_t

typedef void *(* ecs_os_api_realloc_t) (void *ptr, ecs_size_t size)

OS API realloc function type.

Definition at line 89 of file os_api.h.

ecs_os_api_sleep_t

typedef void(* ecs_os_api_sleep_t) (int32_t sec, int32_t nanosec)

OS API sleep function type.

Definition at line 195 of file os_api.h.

ecs_os_api_strdup_t

typedef char *(* ecs_os_api_strdup_t) (const char *str)

OS API strdup function type.

Definition at line 100 of file os_api.h.

ecs_os_api_task_join_t

typedef void *(* ecs_os_api_task_join_t) (ecs_os_thread_t thread)

OS API task_join function type.

Definition at line 131 of file os_api.h.

ecs_os_api_task_new_t

typedef ecs_os_thread_t(* ecs_os_api_task_new_t) (ecs_os_thread_callback_t callback, void *param)

OS API task_new function type.

Definition at line 125 of file os_api.h.

ecs_os_api_thread_join_t

typedef void *(* ecs_os_api_thread_join_t) (ecs_os_thread_t thread)

OS API thread_join function type.

Definition at line 116 of file os_api.h.

ecs_os_api_thread_new_t

typedef ecs_os_thread_t(* ecs_os_api_thread_new_t) (ecs_os_thread_callback_t callback, void *param)

OS API thread_new function type.

Definition at line 110 of file os_api.h.

ecs_os_api_thread_self_t

typedef ecs_os_thread_id_t(* ecs_os_api_thread_self_t) (void)

OS API thread_self function type.

Definition at line 121 of file os_api.h.

ecs_os_cond_t

typedef uintptr_t ecs_os_cond_t

OS cond.

Definition at line 58 of file os_api.h.

ecs_os_dl_t

typedef uintptr_t ecs_os_dl_t

OS dynamic library.

Definition at line 60 of file os_api.h.

ecs_os_mutex_t

typedef uintptr_t ecs_os_mutex_t

OS mutex.

Definition at line 59 of file os_api.h.

ecs_os_proc_t

typedef void(* ecs_os_proc_t) (void)

Generic function pointer type.

Definition at line 67 of file os_api.h.

ecs_os_sock_t

typedef uintptr_t ecs_os_sock_t

OS socket.

Definition at line 61 of file os_api.h.

ecs_os_thread_callback_t

typedef void *(* ecs_os_thread_callback_t) (void *)

OS API thread_callback function type.

Definition at line 105 of file os_api.h.

ecs_os_thread_id_t

typedef uint64_t ecs_os_thread_id_t

64-bit thread ID.

Definition at line 64 of file os_api.h.

ecs_os_thread_t

typedef uintptr_t ecs_os_thread_t

Use handle types that at least can store pointers.

OS thread.

Definition at line 57 of file os_api.h.

Function Documentation

ecs_os_dbg()

FLECS_API void ecs_os_dbg	(	const char *	file,
		int32_t	line,
		const char *	msg )

Macro utilities.

Log at debug level.

Parameters

file	The source file.
line	The source line.
msg	The message to log.

ecs_os_err()

FLECS_API void ecs_os_err	(	const char *	file,
		int32_t	line,
		const char *	msg )

Log at error level.

Parameters

file	The source file.
line	The source line.
msg	The message to log.

ecs_os_fatal()

FLECS_API void ecs_os_fatal	(	const char *	file,
		int32_t	line,
		const char *	msg )

Log at fatal level.

Parameters

file	The source file.
line	The source line.
msg	The message to log.

ecs_os_fini()

FLECS_API void ecs_os_fini

(

void

)

Deinitialize the OS API.

This operation is not usually called by an application.

ecs_os_get_api()

FLECS_API ecs_os_api_t ecs_os_get_api

(

void

)

Get the OS API.

Returns

A value with the current OS API callbacks.

See also

ecs_os_init()

ecs_os_init()

FLECS_API void ecs_os_init

(

void

)

Initialize the OS API.

This operation is not usually called by an application. To override callbacks of the OS API, use the following pattern:

ecs_os_set_api_defaults();
ecs_os_api_t os_api = ecs_os_get_api();
os_api.abort_ = my_abort;
ecs_os_set_api(&os_api);

ecs_os_memdup()

FLECS_API void * ecs_os_memdup	(	const void *	src,
		ecs_size_t	size )

Return newly allocated memory that contains a copy of src.

Parameters

src	The source pointer.
size	The number of bytes to copy.

Returns

The duplicated memory.

ecs_os_perf_trace_pop_()

void ecs_os_perf_trace_pop_	(	const char *	file,
		size_t	line,
		const char *	name )

Pop a performance trace region.

Parameters

file	The source file name.
line	The source line number.
name	The name of the trace region.

ecs_os_perf_trace_push_()

void ecs_os_perf_trace_push_	(	const char *	file,
		size_t	line,
		const char *	name )

Push a performance trace region.

Parameters

file	The source file name.
line	The source line number.
name	The name of the trace region.

ecs_os_set_api()

FLECS_API void ecs_os_set_api

(

ecs_os_api_t *

os_api

)

Override the OS API.

This overrides the OS API struct with new values for callbacks. See ecs_os_init() for how to use the function.

Parameters

os_api

Pointer to a struct with values to set.

ecs_os_set_api_defaults()

FLECS_API void ecs_os_set_api_defaults

(

void

)

Set default values for the OS API.

This initializes the OS API struct with default values for callbacks like malloc and free.

See also

ecs_os_init()

ecs_os_strerror()

FLECS_API const char * ecs_os_strerror

(

int

err

)

Convert errno to a string.

Parameters

err	The error number.

Returns

A string describing the error.

ecs_os_strset()

FLECS_API void ecs_os_strset	(	char **	str,
		const char *	value )

A utility for assigning strings.

This operation frees an existing string and duplicates the input string.

Parameters

str	Pointer to a string value.
value	The string value to assign.

ecs_os_trace()

FLECS_API void ecs_os_trace	(	const char *	file,
		int32_t	line,
		const char *	msg )

Log at trace level.

Parameters

file	The source file.
line	The source line.
msg	The message to log.

ecs_os_warn()

FLECS_API void ecs_os_warn	(	const char *	file,
		int32_t	line,
		const char *	msg )

Log at warning level.

Parameters

file	The source file.
line	The source line.
msg	The message to log.

ecs_sleepf()

FLECS_API void ecs_sleepf

(

double

t

)

Sleep with floating-point time.

Parameters

t	The time in seconds.

ecs_time_measure()

FLECS_API double ecs_time_measure

(

ecs_time_t *

start

)

Measure time since the provided timestamp.

Use with a time value initialized to 0 to obtain the number of seconds since the epoch. The operation will write the current timestamp into start.

Usage:

ecs_time_t t = {};
ecs_time_measure(&t);
// code
double elapsed = ecs_time_measure(&t);

Parameters

start

The starting timestamp.

Returns

The time elapsed since start.

ecs_time_sub()

FLECS_API ecs_time_t ecs_time_sub	(	ecs_time_t	t1,
		ecs_time_t	t2 )

Calculate the difference between two timestamps.

Parameters

t1	The first timestamp.
t2	The second timestamp.

Returns

The difference between timestamps.

ecs_time_to_double()

FLECS_API double ecs_time_to_double

(

ecs_time_t

t

)

Convert a time value to a double.

Parameters

t	The timestamp.

Returns

The timestamp converted to a double.

Variable Documentation

ecs_os_api_malloc_count

int64_t ecs_os_api_malloc_count

extern

Allocation counters.

malloc count.