Skip to content
Flecs v4.2
os_api.h
Go to the documentation of this file.
1/**
2 * @file os_api.h
3 * @brief Operating system abstraction API.
4 *
5 * This file contains the operating system abstraction API. The flecs core
6 * library avoids OS/runtime-specific API calls as much as possible. Instead, it
7 * provides an interface that can be implemented by applications.
8 *
9 * Examples of how to implement this interface can be found in the
10 * examples/os_api folder.
11 */
12
13#ifndef FLECS_OS_API_H
14#define FLECS_OS_API_H
15
16/**
17 * @defgroup c_os_api OS API
18 * @ingroup c
19 * Interface for providing OS-specific functionality.
20 *
21 * @{
22 */
23
24#if defined(ECS_TARGET_WINDOWS)
25#include <malloc.h>
26#elif defined(ECS_TARGET_FREEBSD)
27#include <stdlib.h>
28#else
29#include <alloca.h>
30#endif
31
32#include <stdio.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/** Time type. */
39typedef struct ecs_time_t {
40 uint32_t sec; /**< Second part. */
41 uint32_t nanosec; /**< Nanosecond part. */
43
44/** Allocation counters. */
45FLECS_API extern int64_t ecs_os_api_malloc_count; /**< malloc count. */
46FLECS_API extern int64_t ecs_os_api_realloc_count; /**< realloc count. */
47FLECS_API extern int64_t ecs_os_api_calloc_count; /**< calloc count. */
48FLECS_API extern int64_t ecs_os_api_free_count; /**< free count. */
49
50/* Enabling this flag will add a header to each allocation that allows the code
51 * to track exactly how much memory has been allocated. Increases memory
52 * utilization by 16 bytes per allocation, and is not thread-safe. */
53// #define FLECS_TRACK_OS_ALLOC
54#ifdef FLECS_TRACK_OS_ALLOC
55FLECS_API extern ecs_size_t ecs_os_allocated_bytes;
56#endif
57
58/** Use handle types that _at least_ can store pointers. */
59typedef uintptr_t ecs_os_thread_t; /**< OS thread. */
60typedef uintptr_t ecs_os_cond_t; /**< OS cond. */
61typedef uintptr_t ecs_os_mutex_t; /**< OS mutex. */
62typedef uintptr_t ecs_os_dl_t; /**< OS dynamic library. */
63typedef uintptr_t ecs_os_sock_t; /**< OS socket. */
64
65/** 64-bit thread ID. */
66typedef uint64_t ecs_os_thread_id_t;
67
68/** Generic function pointer type. */
69typedef void (*ecs_os_proc_t)(void);
70
71/** OS API init. */
72typedef
73void (*ecs_os_api_init_t)(void);
74
75/** OS API deinit. */
76typedef
77void (*ecs_os_api_fini_t)(void);
78
79/** OS API malloc function type. */
80typedef
81void* (*ecs_os_api_malloc_t)(
82 ecs_size_t size);
83
84/** OS API free function type. */
85typedef
87 void *ptr);
88
89/** OS API realloc function type. */
90typedef
91void* (*ecs_os_api_realloc_t)(
92 void *ptr,
93 ecs_size_t size);
94
95/** OS API calloc function type. */
96typedef
97void* (*ecs_os_api_calloc_t)(
98 ecs_size_t size);
99
100/** OS API strdup function type. */
101typedef
102char* (*ecs_os_api_strdup_t)(
103 const char *str);
104
105/** OS API thread_callback function type. */
106typedef
107void* (*ecs_os_thread_callback_t)(
108 void*);
109
110/** OS API thread_new function type. */
111typedef
114 void *param);
115
116/** OS API thread_join function type. */
117typedef
118void* (*ecs_os_api_thread_join_t)(
119 ecs_os_thread_t thread);
120
121/** OS API thread_self function type. */
122typedef
124
125/** OS API task_new function type. */
126typedef
129 void *param);
130
131/** OS API task_join function type. */
132typedef
133void* (*ecs_os_api_task_join_t)(
134 ecs_os_thread_t thread);
135
136/** Atomic increment and decrement. */
137/** OS API ainc function type. */
138typedef
140 int32_t *value);
141
142/** OS API lainc function type. */
143typedef
145 int64_t *value);
146
147/** Mutex. */
148/** OS API mutex_new function type. */
149typedef
151 void);
152
153/** OS API mutex_lock function type. */
154typedef
156 ecs_os_mutex_t mutex);
157
158/** OS API mutex_unlock function type. */
159typedef
161 ecs_os_mutex_t mutex);
162
163/** OS API mutex_free function type. */
164typedef
166 ecs_os_mutex_t mutex);
167
168/** Condition variable. */
169/** OS API cond_new function type. */
170typedef
172 void);
173
174/** OS API cond_free function type. */
175typedef
177 ecs_os_cond_t cond);
178
179/** OS API cond_signal function type. */
180typedef
182 ecs_os_cond_t cond);
183
184/** OS API cond_broadcast function type. */
185typedef
187 ecs_os_cond_t cond);
188
189/** OS API cond_wait function type. */
190typedef
192 ecs_os_cond_t cond,
193 ecs_os_mutex_t mutex);
194
195typedef
196bool (*ecs_os_api_cond_timedwait_t)(
197 ecs_os_cond_t cond,
198 ecs_os_mutex_t mutex,
199 int32_t sec,
200 int32_t nanosec);
201
202/** OS API sleep function type. */
203typedef
205 int32_t sec,
206 int32_t nanosec);
207
208/** OS API enable_high_timer_resolution function type. */
209typedef
211 bool enable);
212
213/** OS API get_time function type. */
214typedef
216 ecs_time_t *time_out);
217
218/** OS API now function type. */
219typedef
220uint64_t (*ecs_os_api_now_t)(void);
221
222/** OS API log function type.
223 *
224 * @param level The logging level.
225 * @param file The file where the message was logged.
226 * @param line The line where it was logged.
227 * @param msg The log message.
228 */
229typedef
231 int32_t level,
232 const char *file,
233 int32_t line,
234 const char *msg);
235
236/** OS API abort function type. */
237typedef
239 void);
240
241/** OS API dlopen function type. */
242typedef
244 const char *libname);
245
246/** OS API dlproc function type. */
247typedef
249 ecs_os_dl_t lib,
250 const char *procname);
251
252/** OS API dlclose function type. */
253typedef
255 ecs_os_dl_t lib);
256
257/** OS API module_to_path function type. */
258typedef
259char* (*ecs_os_api_module_to_path_t)(
260 const char *module_id);
261
262/** OS API fopen function type. */
263typedef
264FILE* (*ecs_os_api_fopen_t)(
265 const char *file,
266 const char *mode);
267
268/** OS API fclose function type. */
269typedef
271 FILE *file);
272
273/** OS API fread function type. */
274typedef
276 void *ptr,
277 size_t size,
278 size_t count,
279 FILE *file);
280
281/** OS API fwrite function type. */
282typedef
284 const void *ptr,
285 size_t size,
286 size_t count,
287 FILE *file);
288
289/** OS API mkdir function type.
290 * Returns 0 if the directory was created or already exists.
291 */
292typedef
294 const char *path);
295
296/** OS API remove function type.
297 * Used to remove a file (remove_) or an empty directory (rmdir_). Returns 0 if
298 * the file or directory was removed.
299 */
300typedef
302 const char *path);
303
304/** OS API performance tracing function type.
305 *
306 * @param filename The source file name.
307 * @param line The source line number.
308 * @param name The name of the trace region.
309 */
311 const char *filename,
312 size_t line,
313 const char *name);
314
315/* Prefix members of the struct with 'ecs_' as some system headers may define
316 * macros for functions like "strdup", "log", or "_free". */
317
318/** OS API interface. */
319typedef struct ecs_os_api_t {
320 /* API init and deinit */
321 ecs_os_api_init_t init_; /**< init callback. */
322 ecs_os_api_fini_t fini_; /**< fini callback. */
323
324 /* Memory management */
325 ecs_os_api_malloc_t malloc_; /**< malloc callback. */
326 ecs_os_api_realloc_t realloc_; /**< realloc callback. */
327 ecs_os_api_calloc_t calloc_; /**< calloc callback. */
328 ecs_os_api_free_t free_; /**< free callback. */
329
330 /* Strings */
331 ecs_os_api_strdup_t strdup_; /**< strdup callback. */
332
333 /* Threads */
334 ecs_os_api_thread_new_t thread_new_; /**< thread_new callback. */
335 ecs_os_api_thread_join_t thread_join_; /**< thread_join callback. */
336 ecs_os_api_thread_self_t thread_self_; /**< thread_self callback. */
337
338 /* Tasks */
339 ecs_os_api_thread_new_t task_new_; /**< task_new callback. */
340 ecs_os_api_thread_join_t task_join_; /**< task_join callback. */
341
342 /* Atomic increment and decrement */
343 ecs_os_api_ainc_t ainc_; /**< ainc callback. */
344 ecs_os_api_ainc_t adec_; /**< adec callback. */
345 ecs_os_api_lainc_t lainc_; /**< lainc callback. */
346 ecs_os_api_lainc_t ladec_; /**< ladec callback. */
347
348 /* Mutex */
349 ecs_os_api_mutex_new_t mutex_new_; /**< mutex_new callback. */
350 ecs_os_api_mutex_free_t mutex_free_; /**< mutex_free callback. */
351 ecs_os_api_mutex_lock_t mutex_lock_; /**< mutex_lock callback. */
352 ecs_os_api_mutex_lock_t mutex_unlock_; /**< mutex_unlock callback. */
353
354 /* Condition variable */
355 ecs_os_api_cond_new_t cond_new_; /**< cond_new callback. */
356 ecs_os_api_cond_free_t cond_free_; /**< cond_free callback. */
357 ecs_os_api_cond_signal_t cond_signal_; /**< cond_signal callback. */
358 ecs_os_api_cond_broadcast_t cond_broadcast_; /**< cond_broadcast callback. */
359 ecs_os_api_cond_wait_t cond_wait_; /**< cond_wait callback. */
360 ecs_os_api_cond_timedwait_t cond_timedwait_;
361
362 /* Time */
363 ecs_os_api_sleep_t sleep_; /**< sleep callback. */
364 ecs_os_api_now_t now_; /**< now callback. */
365 ecs_os_api_get_time_t get_time_; /**< get_time callback. */
366
367 /* Logging */
368 ecs_os_api_log_t log_; /**< log callback.
369 * The level should be interpreted as:
370 * >0: Debug tracing. Only enabled in debug builds.
371 * 0: Tracing. Enabled in debug and release builds.
372 * -2: Warning. An issue occurred, but the operation was successful.
373 * -3: Error. An issue occurred, and the operation was unsuccessful.
374 * -4: Fatal. An issue occurred, and the application must quit. */
375
376 /* Application termination */
377 ecs_os_api_abort_t abort_; /**< abort callback. */
378
379 /* Dynamic library loading */
380 ecs_os_api_dlopen_t dlopen_; /**< dlopen callback. */
381 ecs_os_api_dlproc_t dlproc_; /**< dlproc callback. */
382 ecs_os_api_dlclose_t dlclose_; /**< dlclose callback. */
383
384 /* Overridable function that translates from a logical module ID to a
385 * shared library filename. */
386 ecs_os_api_module_to_path_t module_to_dl_; /**< module_to_dl callback. */
387
388 /* Overridable function that translates from a logical module ID to a
389 * path that contains module-specific resources or assets. */
390 ecs_os_api_module_to_path_t module_to_etc_; /**< module_to_etc callback. */
391
392 /* File I/O */
393 ecs_os_api_fopen_t fopen_; /**< fopen callback. */
394 ecs_os_api_fclose_t fclose_; /**< fclose callback. */
395 ecs_os_api_fread_t fread_; /**< fread callback. */
396 ecs_os_api_fwrite_t fwrite_; /**< fwrite callback. */
397 ecs_os_api_mkdir_t mkdir_; /**< mkdir callback. */
398 ecs_os_api_remove_t rmdir_; /**< rmdir callback. */
399 ecs_os_api_remove_t remove_; /**< remove callback. */
400
401 /* Performance tracing */
402 ecs_os_api_perf_trace_t perf_trace_push_; /**< perf_trace_push callback. */
403 ecs_os_api_perf_trace_t perf_trace_pop_; /**< perf_trace_pop callback. */
404
405 int32_t log_level_; /**< Tracing level. */
406 int32_t log_indent_; /**< Tracing indentation level. */
407 int32_t log_last_error_; /**< Last logged error code. */
408 int64_t log_last_timestamp_; /**< Last logged timestamp. */
409
410 ecs_flags32_t flags_; /**< OS API flags. */
411
412 void *log_out_; /**< File used for logging output (type is FILE*)
413 * (hint: log_ decides where to write). */
415
416/** Static OS API variable with configured callbacks. */
417FLECS_API
419
420/** Initialize the OS API.
421 * This operation is not usually called by an application. To override callbacks
422 * of the OS API, use the following pattern:
423 *
424 * @code
425 * ecs_os_set_api_defaults();
426 * ecs_os_api_t os_api = ecs_os_get_api();
427 * os_api.abort_ = my_abort;
428 * ecs_os_set_api(&os_api);
429 * @endcode
430 */
431FLECS_API
432void ecs_os_init(void);
433
434/** Deinitialize the OS API.
435 * This operation is not usually called by an application.
436 */
437FLECS_API
438void ecs_os_fini(void);
439
440/** Override the OS API.
441 * This overrides the OS API struct with new values for callbacks. See
442 * ecs_os_init() for how to use the function.
443 *
444 * @param os_api Pointer to a struct with values to set.
445 */
446FLECS_API
448 ecs_os_api_t *os_api);
449
450/** Get the OS API.
451 *
452 * @return A value with the current OS API callbacks.
453 * @see ecs_os_init()
454 */
455FLECS_API
457
458/** Set default values for the OS API.
459 * This initializes the OS API struct with default values for callbacks like
460 * malloc and free.
461 *
462 * @see ecs_os_init()
463 */
464FLECS_API
466
467/** Macro utilities
468 * \cond
469 */
470
471/* Memory management */
472#ifndef ecs_os_malloc
473#define ecs_os_malloc(size) ecs_os_api.malloc_(size)
474#endif
475#ifndef ecs_os_free
476#define ecs_os_free(ptr) ecs_os_api.free_(ptr)
477#endif
478#ifndef ecs_os_realloc
479#define ecs_os_realloc(ptr, size) ecs_os_api.realloc_(ptr, size)
480#endif
481#ifndef ecs_os_calloc
482#define ecs_os_calloc(size) ecs_os_api.calloc_(size)
483#endif
484#if defined(ECS_TARGET_WINDOWS)
485#define ecs_os_alloca(size) _alloca((size_t)(size))
486#else
487#define ecs_os_alloca(size) alloca((size_t)(size))
488#endif
489
490#define ecs_os_malloc_t(T) ECS_CAST(T*, ecs_os_malloc(ECS_SIZEOF(T)))
491#define ecs_os_malloc_n(T, count) ECS_CAST(T*, ecs_os_malloc(ECS_SIZEOF(T) * (count)))
492#define ecs_os_calloc_t(T) ECS_CAST(T*, ecs_os_calloc(ECS_SIZEOF(T)))
493#define ecs_os_calloc_n(T, count) ECS_CAST(T*, ecs_os_calloc(ECS_SIZEOF(T) * (count)))
494
495#define ecs_os_realloc_t(ptr, T) ECS_CAST(T*, ecs_os_realloc(ptr, ECS_SIZEOF(T)))
496#define ecs_os_realloc_n(ptr, T, count) ECS_CAST(T*, ecs_os_realloc(ptr, ECS_SIZEOF(T) * (count)))
497#define ecs_os_alloca_t(T) ECS_CAST(T*, ecs_os_alloca(ECS_SIZEOF(T)))
498#define ecs_os_alloca_n(T, count) ECS_CAST(T*, ecs_os_alloca(ECS_SIZEOF(T) * (count)))
499
500/* Strings */
501#ifndef ecs_os_strdup
502#define ecs_os_strdup(str) ecs_os_strdup_(str)
503#endif
504
505#ifdef __cplusplus
506#define ecs_os_strlen(str) static_cast<ecs_size_t>(strlen(str))
507#define ecs_os_strncmp(str1, str2, num) strncmp(str1, str2, static_cast<size_t>(num))
508#define ecs_os_memcmp(ptr1, ptr2, num) memcmp(ptr1, ptr2, static_cast<size_t>(num))
509#define ecs_os_memcpy(ptr1, ptr2, num) memcpy(ptr1, ptr2, static_cast<size_t>(num))
510#define ecs_os_memset(ptr, value, num) memset(ptr, value, static_cast<size_t>(num))
511#define ecs_os_memmove(dst, src, size) memmove(dst, src, static_cast<size_t>(size))
512#else
513#define ecs_os_strlen(str) (ecs_size_t)strlen(str)
514#define ecs_os_strncmp(str1, str2, num) strncmp(str1, str2, (size_t)(num))
515#define ecs_os_memcmp(ptr1, ptr2, num) memcmp(ptr1, ptr2, (size_t)(num))
516#define ecs_os_memcpy(ptr1, ptr2, num) memcpy(ptr1, ptr2, (size_t)(num))
517#define ecs_os_memset(ptr, value, num) memset(ptr, value, (size_t)(num))
518#define ecs_os_memmove(dst, src, size) memmove(dst, src, (size_t)(size))
519#endif
520
521#define ecs_os_memcpy_t(ptr1, ptr2, T) ecs_os_memcpy(ptr1, ptr2, ECS_SIZEOF(T))
522#define ecs_os_memcpy_n(ptr1, ptr2, T, count) ecs_os_memcpy(ptr1, ptr2, ECS_SIZEOF(T) * (size_t)(count))
523#define ecs_os_memcmp_t(ptr1, ptr2, T) ecs_os_memcmp(ptr1, ptr2, ECS_SIZEOF(T))
524
525#define ecs_os_memmove_t(ptr1, ptr2, T) ecs_os_memmove(ptr1, ptr2, ECS_SIZEOF(T))
526#define ecs_os_memmove_n(ptr1, ptr2, T, count) ecs_os_memmove(ptr1, ptr2, ECS_SIZEOF(T) * (size_t)(count))
527
528#define ecs_os_strcmp(str1, str2) strcmp(str1, str2)
529#define ecs_os_memset_t(ptr, value, T) ecs_os_memset(ptr, value, ECS_SIZEOF(T))
530#define ecs_os_memset_n(ptr, value, T, count) ecs_os_memset(ptr, value, ECS_SIZEOF(T) * (size_t)(count))
531#define ecs_os_zeromem(ptr) ecs_os_memset(ptr, 0, ECS_SIZEOF(*ptr))
532
533#define ecs_os_memdup_t(ptr, T) ecs_os_memdup(ptr, ECS_SIZEOF(T))
534#define ecs_os_memdup_n(ptr, T, count) ecs_os_memdup(ptr, ECS_SIZEOF(T) * (count))
535
536#define ecs_offset(ptr, T, index)\
537 ECS_CAST(T*, ECS_OFFSET(ptr, ECS_SIZEOF(T) * (index)))
538
539#if !defined(ECS_TARGET_POSIX) && !defined(ECS_TARGET_MINGW)
540#define ecs_os_strcat(str1, str2) strcat_s(str1, INT_MAX, str2)
541#define ecs_os_snprintf(ptr, len, ...) sprintf_s(ptr, ECS_CAST(size_t, len), __VA_ARGS__)
542#define ecs_os_vsnprintf(ptr, len, fmt, args) vsnprintf(ptr, ECS_CAST(size_t, len), fmt, args)
543#define ecs_os_strcpy(str1, str2) strcpy_s(str1, INT_MAX, str2)
544#define ecs_os_strncpy(str1, str2, len) strncpy_s(str1, INT_MAX, str2, ECS_CAST(size_t, len))
545#else
546#define ecs_os_strcat(str1, str2) strcat(str1, str2)
547#define ecs_os_snprintf(ptr, len, ...) snprintf(ptr, ECS_CAST(size_t, len), __VA_ARGS__)
548#define ecs_os_vsnprintf(ptr, len, fmt, args) vsnprintf(ptr, ECS_CAST(size_t, len), fmt, args)
549#define ecs_os_strcpy(str1, str2) strcpy(str1, str2)
550#define ecs_os_strncpy(str1, str2, len) strncpy(str1, str2, ECS_CAST(size_t, len))
551#endif
552
553/* Files */
554#define ecs_os_fopen(file, mode) ecs_os_api.fopen_(file, mode)
555#define ecs_os_fclose(file) ecs_os_api.fclose_(file)
556#define ecs_os_fread(ptr, size, count, file) ecs_os_api.fread_(ptr, size, count, file)
557#define ecs_os_fwrite(ptr, size, count, file) ecs_os_api.fwrite_(ptr, size, count, file)
558#define ecs_os_mkdir(path) ecs_os_api.mkdir_(path)
559#define ecs_os_rmdir(path) ecs_os_api.rmdir_(path)
560#define ecs_os_remove(path) ecs_os_api.remove_(path)
561
562/* Threads */
563#define ecs_os_thread_new(callback, param) ecs_os_api.thread_new_(callback, param)
564#define ecs_os_thread_join(thread) ecs_os_api.thread_join_(thread)
565#define ecs_os_thread_self() ecs_os_api.thread_self_()
566
567/* Tasks */
568#define ecs_os_task_new(callback, param) ecs_os_api.task_new_(callback, param)
569#define ecs_os_task_join(thread) ecs_os_api.task_join_(thread)
570
571/* Atomic increment and decrement */
572#define ecs_os_ainc(value) ecs_os_api.ainc_(value)
573#define ecs_os_adec(value) ecs_os_api.adec_(value)
574#define ecs_os_lainc(value) ecs_os_api.lainc_(value)
575#define ecs_os_ladec(value) ecs_os_api.ladec_(value)
576
577/* Mutex */
578#define ecs_os_mutex_new() ecs_os_api.mutex_new_()
579#define ecs_os_mutex_free(mutex) ecs_os_api.mutex_free_(mutex)
580#define ecs_os_mutex_lock(mutex) ecs_os_api.mutex_lock_(mutex)
581#define ecs_os_mutex_unlock(mutex) ecs_os_api.mutex_unlock_(mutex)
582
583/* Condition variable */
584#define ecs_os_cond_new() ecs_os_api.cond_new_()
585#define ecs_os_cond_free(cond) ecs_os_api.cond_free_(cond)
586#define ecs_os_cond_signal(cond) ecs_os_api.cond_signal_(cond)
587#define ecs_os_cond_broadcast(cond) ecs_os_api.cond_broadcast_(cond)
588#define ecs_os_cond_wait(cond, mutex) ecs_os_api.cond_wait_(cond, mutex)
589#define ecs_os_cond_timedwait(cond, mutex, sec, nanosec) \
590 ecs_os_api.cond_timedwait_(cond, mutex, sec, nanosec)
591
592/* Time */
593#define ecs_os_sleep(sec, nanosec) ecs_os_api.sleep_(sec, nanosec)
594#define ecs_os_now() ecs_os_api.now_()
595#define ecs_os_get_time(time_out) ecs_os_api.get_time_(time_out)
596
597#ifndef FLECS_DISABLE_COUNTERS
598#ifdef FLECS_ACCURATE_COUNTERS
599#define ecs_os_inc(v) (ecs_os_ainc(v))
600#define ecs_os_linc(v) (ecs_os_lainc(v))
601#define ecs_os_dec(v) (ecs_os_adec(v))
602#define ecs_os_ldec(v) (ecs_os_ladec(v))
603#else
604#define ecs_os_inc(v) (++(*v))
605#define ecs_os_linc(v) (++(*v))
606#define ecs_os_dec(v) (--(*v))
607#define ecs_os_ldec(v) (--(*v))
608#endif
609#else
610#define ecs_os_inc(v)
611#define ecs_os_linc(v)
612#define ecs_os_dec(v)
613#define ecs_os_ldec(v)
614#endif
615
616
617#ifdef ECS_TARGET_MINGW
618/* mingw bug: without this, a conversion error is thrown, but isnan/isinf should
619 * accept float, double, and long double. */
620#define ecs_os_isnan(val) (isnan((float)val))
621#define ecs_os_isinf(val) (isinf((float)val))
622#else
623#define ecs_os_isnan(val) (isnan(val))
624#define ecs_os_isinf(val) (isinf(val))
625#endif
626
627/* Application termination */
628#define ecs_os_abort() ecs_os_api.abort_()
629
630/* Dynamic libraries */
631#define ecs_os_dlopen(libname) ecs_os_api.dlopen_(libname)
632#define ecs_os_dlproc(lib, procname) ecs_os_api.dlproc_(lib, procname)
633#define ecs_os_dlclose(lib) ecs_os_api.dlclose_(lib)
634
635/* Module ID translation */
636#define ecs_os_module_to_dl(lib) ecs_os_api.module_to_dl_(lib)
637#define ecs_os_module_to_etc(lib) ecs_os_api.module_to_etc_(lib)
638
639/** Macro utilities
640 * \endcond
641 */
642
643
644/* Logging */
645
646/** Log at debug level.
647 *
648 * @param file The source file.
649 * @param line The source line.
650 * @param msg The message to log.
651*/
652FLECS_API
654 const char *file,
655 int32_t line,
656 const char *msg);
657
658/** Log at trace level.
659 *
660 * @param file The source file.
661 * @param line The source line.
662 * @param msg The message to log.
663*/
664FLECS_API
666 const char *file,
667 int32_t line,
668 const char *msg);
669
670/** Log at warning level.
671 *
672 * @param file The source file.
673 * @param line The source line.
674 * @param msg The message to log.
675*/
676FLECS_API
678 const char *file,
679 int32_t line,
680 const char *msg);
681
682/** Log at error level.
683 *
684 * @param file The source file.
685 * @param line The source line.
686 * @param msg The message to log.
687*/
688FLECS_API
690 const char *file,
691 int32_t line,
692 const char *msg);
693
694/** Log at fatal level.
695 *
696 * @param file The source file.
697 * @param line The source line.
698 * @param msg The message to log.
699*/
700FLECS_API
702 const char *file,
703 int32_t line,
704 const char *msg);
705
706/** Convert errno to a string.
707 *
708 * @param err The error number.
709 * @return A string describing the error.
710 */
711FLECS_API
712const char* ecs_os_strerror(
713 int err);
714
715/** A utility for assigning strings.
716 * This operation frees an existing string and duplicates the input string.
717 *
718 * @param str Pointer to a string value.
719 * @param value The string value to assign.
720 */
721FLECS_API
723 char **str,
724 const char *value);
725
726FLECS_API
727char* ecs_os_strdup_(
728 const char *str);
729
730/* Profile tracing */
731#ifdef FLECS_PERF_TRACE
732#define ecs_os_perf_trace_push(name) ecs_os_perf_trace_push_(__FILE__, __LINE__, name)
733#define ecs_os_perf_trace_pop(name) ecs_os_perf_trace_pop_(__FILE__, __LINE__, name)
734#else
735#define ecs_os_perf_trace_push(name)
736#define ecs_os_perf_trace_pop(name)
737#endif
738
739/** Push a performance trace region.
740 *
741 * @param file The source file name.
742 * @param line The source line number.
743 * @param name The name of the trace region.
744 */
746 const char *file,
747 size_t line,
748 const char *name);
749
750/** Pop a performance trace region.
751 *
752 * @param file The source file name.
753 * @param line The source line number.
754 * @param name The name of the trace region.
755 */
757 const char *file,
758 size_t line,
759 const char *name);
760
761/** Sleep with floating-point time.
762 *
763 * @param t The time in seconds.
764 */
765FLECS_API
767 double t);
768
769/** Measure time since the provided timestamp.
770 * Use with a time value initialized to 0 to obtain the number of seconds since
771 * the epoch. The operation will write the current timestamp into start.
772 *
773 * Usage:
774 * @code
775 * ecs_time_t t = {};
776 * ecs_time_measure(&t);
777 * // code
778 * double elapsed = ecs_time_measure(&t);
779 * @endcode
780 *
781 * @param start The starting timestamp.
782 * @return The time elapsed since start.
783 */
784FLECS_API
786 ecs_time_t *start);
787
788/** Calculate the difference between two timestamps.
789 *
790 * @param t1 The first timestamp.
791 * @param t2 The second timestamp.
792 * @return The difference between timestamps.
793 */
794FLECS_API
796 ecs_time_t t1,
797 ecs_time_t t2);
798
799/** Convert a time value to a double.
800 *
801 * @param t The timestamp.
802 * @return The timestamp converted to a double.
803 */
804FLECS_API
806 ecs_time_t t);
807
808/** Return newly allocated memory that contains a copy of src.
809 *
810 * @param src The source pointer.
811 * @param size The number of bytes to copy.
812 * @return The duplicated memory.
813 */
814FLECS_API
816 const void *src,
817 ecs_size_t size);
818
819/** Are heap functions available? */
820FLECS_API
822
823/** Are threading functions available? */
824FLECS_API
826
827/** Are task functions available? */
828FLECS_API
830
831/** Are time functions available? */
832FLECS_API
834
835/** Are logging functions available? */
836FLECS_API
838
839/** Are dynamic library functions available? */
840FLECS_API
841bool ecs_os_has_dl(void);
842
843/** Are module path functions available? */
844FLECS_API
846
847/** Are directory and file removal functions available? */
848FLECS_API
850
851#ifdef __cplusplus
852}
853#endif
854
855/** @} */
856
857#endif
size_t(*) ecs_os_api_fread_t(void *ptr, size_t size, size_t count, FILE *file)
OS API fread function type.
Definition os_api.h:275
void *(*) ecs_os_api_calloc_t(ecs_size_t size)
OS API calloc function type.
Definition os_api.h:97
FLECS_API void ecs_os_err(const char *file, int32_t line, const char *msg)
Log at error level.
void(*) ecs_os_api_abort_t(void)
OS API abort function type.
Definition os_api.h:238
char *(*) ecs_os_api_module_to_path_t(const char *module_id)
OS API module_to_path function type.
Definition os_api.h:259
uintptr_t ecs_os_dl_t
OS dynamic library.
Definition os_api.h:62
uint64_t ecs_os_thread_id_t
64-bit thread ID.
Definition os_api.h:66
void(*) ecs_os_api_enable_high_timer_resolution_t(bool enable)
OS API enable_high_timer_resolution function type.
Definition os_api.h:210
FLECS_API ecs_os_api_t ecs_os_api
Static OS API variable with configured callbacks.
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 os_api.h:127
void(*) ecs_os_api_mutex_unlock_t(ecs_os_mutex_t mutex)
OS API mutex_unlock function type.
Definition os_api.h:160
ecs_os_mutex_t(*) ecs_os_api_mutex_new_t(void)
Mutex.
Definition os_api.h:150
uint64_t(*) ecs_os_api_now_t(void)
OS API now function type.
Definition os_api.h:220
int32_t(*) ecs_os_api_ainc_t(int32_t *value)
Atomic increment and decrement.
Definition os_api.h:139
void(*) ecs_os_api_cond_broadcast_t(ecs_os_cond_t cond)
OS API cond_broadcast function type.
Definition os_api.h:186
ecs_os_dl_t(*) ecs_os_api_dlopen_t(const char *libname)
OS API dlopen function type.
Definition os_api.h:243
FLECS_API int64_t ecs_os_api_realloc_count
realloc count.
void *(*) ecs_os_thread_callback_t(void *)
OS API thread_callback function type.
Definition os_api.h:107
FLECS_API double ecs_time_measure(ecs_time_t *start)
Measure time since the provided timestamp.
FLECS_API bool ecs_os_has_time(void)
Are time functions available?
FLECS_API bool ecs_os_has_dl(void)
Are dynamic library functions available?
char *(*) ecs_os_api_strdup_t(const char *str)
OS API strdup function type.
Definition os_api.h:102
FLECS_API bool ecs_os_has_logging(void)
Are logging functions available?
void(*) ecs_os_api_cond_wait_t(ecs_os_cond_t cond, ecs_os_mutex_t mutex)
OS API cond_wait function type.
Definition os_api.h:191
FLECS_API bool ecs_os_has_modules(void)
Are module path functions available?
void *(*) ecs_os_api_realloc_t(void *ptr, ecs_size_t size)
OS API realloc function type.
Definition os_api.h:91
uintptr_t ecs_os_thread_t
Use handle types that at least can store pointers.
Definition os_api.h:59
void(*) ecs_os_api_dlclose_t(ecs_os_dl_t lib)
OS API dlclose function type.
Definition os_api.h:254
uintptr_t ecs_os_sock_t
OS socket.
Definition os_api.h:63
void(*) ecs_os_api_get_time_t(ecs_time_t *time_out)
OS API get_time function type.
Definition os_api.h:215
FLECS_API int64_t ecs_os_api_malloc_count
Allocation counters.
FLECS_API void ecs_os_set_api(ecs_os_api_t *os_api)
Override the OS API.
int(*) ecs_os_api_mkdir_t(const char *path)
OS API mkdir function type.
Definition os_api.h:293
FLECS_API void ecs_os_warn(const char *file, int32_t line, const char *msg)
Log at warning level.
void(*) ecs_os_api_free_t(void *ptr)
OS API free function type.
Definition os_api.h:86
FLECS_API void ecs_os_trace(const char *file, int32_t line, const char *msg)
Log at trace level.
size_t(*) ecs_os_api_fwrite_t(const void *ptr, size_t size, size_t count, FILE *file)
OS API fwrite function type.
Definition os_api.h:283
FLECS_API bool ecs_os_has_task_support(void)
Are task functions available?
FLECS_API ecs_os_api_t ecs_os_get_api(void)
Get the OS API.
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 os_api.h:112
void(*) ecs_os_api_perf_trace_t(const char *filename, size_t line, const char *name)
OS API performance tracing function type.
Definition os_api.h:310
FILE *(*) ecs_os_api_fopen_t(const char *file, const char *mode)
OS API fopen function type.
Definition os_api.h:264
void *(*) ecs_os_api_malloc_t(ecs_size_t size)
OS API malloc function type.
Definition os_api.h:81
ecs_os_thread_id_t(*) ecs_os_api_thread_self_t(void)
OS API thread_self function type.
Definition os_api.h:123
FLECS_API double ecs_time_to_double(ecs_time_t t)
Convert a time value to a double.
FLECS_API int64_t ecs_os_api_free_count
free count.
FLECS_API void ecs_os_strset(char **str, const char *value)
A utility for assigning strings.
void(*) ecs_os_api_fclose_t(FILE *file)
OS API fclose function type.
Definition os_api.h:270
void(*) ecs_os_api_log_t(int32_t level, const char *file, int32_t line, const char *msg)
OS API log function type.
Definition os_api.h:230
FLECS_API void ecs_os_dbg(const char *file, int32_t line, const char *msg)
Macro utilities.
void(*) ecs_os_api_fini_t(void)
OS API deinit.
Definition os_api.h:77
FLECS_API bool ecs_os_has_dirs(void)
Are directory and file removal functions available?
void ecs_os_perf_trace_push_(const char *file, size_t line, const char *name)
Push a performance trace region.
uintptr_t ecs_os_mutex_t
OS mutex.
Definition os_api.h:61
ecs_os_proc_t(*) ecs_os_api_dlproc_t(ecs_os_dl_t lib, const char *procname)
OS API dlproc function type.
Definition os_api.h:248
FLECS_API ecs_time_t ecs_time_sub(ecs_time_t t1, ecs_time_t t2)
Calculate the difference between two timestamps.
void(*) ecs_os_api_sleep_t(int32_t sec, int32_t nanosec)
OS API sleep function type.
Definition os_api.h:204
void(*) ecs_os_api_cond_free_t(ecs_os_cond_t cond)
OS API cond_free function type.
Definition os_api.h:176
uintptr_t ecs_os_cond_t
OS cond.
Definition os_api.h:60
void(*) ecs_os_api_init_t(void)
OS API init.
Definition os_api.h:73
int64_t(*) ecs_os_api_lainc_t(int64_t *value)
OS API lainc function type.
Definition os_api.h:144
void(*) ecs_os_proc_t(void)
Generic function pointer type.
Definition os_api.h:69
FLECS_API bool ecs_os_has_threading(void)
Are threading functions available?
FLECS_API void * ecs_os_memdup(const void *src, ecs_size_t size)
Return newly allocated memory that contains a copy of src.
void(*) ecs_os_api_cond_signal_t(ecs_os_cond_t cond)
OS API cond_signal function type.
Definition os_api.h:181
void *(*) ecs_os_api_thread_join_t(ecs_os_thread_t thread)
OS API thread_join function type.
Definition os_api.h:118
FLECS_API void ecs_os_set_api_defaults(void)
Set default values for the OS API.
FLECS_API void ecs_os_fatal(const char *file, int32_t line, const char *msg)
Log at fatal level.
int(*) ecs_os_api_remove_t(const char *path)
OS API remove function type.
Definition os_api.h:301
FLECS_API void ecs_os_init(void)
Initialize the OS API.
void(*) ecs_os_api_mutex_free_t(ecs_os_mutex_t mutex)
OS API mutex_free function type.
Definition os_api.h:165
FLECS_API bool ecs_os_has_heap(void)
Are heap functions available?
FLECS_API void ecs_os_fini(void)
Deinitialize the OS API.
void ecs_os_perf_trace_pop_(const char *file, size_t line, const char *name)
Pop a performance trace region.
FLECS_API const char * ecs_os_strerror(int err)
Convert errno to a string.
FLECS_API void ecs_sleepf(double t)
Sleep with floating-point time.
void(*) ecs_os_api_mutex_lock_t(ecs_os_mutex_t mutex)
OS API mutex_lock function type.
Definition os_api.h:155
ecs_os_cond_t(*) ecs_os_api_cond_new_t(void)
Condition variable.
Definition os_api.h:171
FLECS_API int64_t ecs_os_api_calloc_count
calloc count.
OS API interface.
Definition os_api.h:319
ecs_os_api_fopen_t fopen_
fopen callback.
Definition os_api.h:393
ecs_os_api_cond_wait_t cond_wait_
cond_wait callback.
Definition os_api.h:359
ecs_os_api_thread_new_t thread_new_
thread_new callback.
Definition os_api.h:334
ecs_os_api_free_t free_
free callback.
Definition os_api.h:328
int32_t log_last_error_
Last logged error code.
Definition os_api.h:407
ecs_os_api_sleep_t sleep_
sleep callback.
Definition os_api.h:363
ecs_os_api_realloc_t realloc_
realloc callback.
Definition os_api.h:326
ecs_os_api_mkdir_t mkdir_
mkdir callback.
Definition os_api.h:397
ecs_os_api_mutex_lock_t mutex_unlock_
mutex_unlock callback.
Definition os_api.h:352
ecs_os_api_abort_t abort_
abort callback.
Definition os_api.h:377
ecs_os_api_lainc_t lainc_
lainc callback.
Definition os_api.h:345
ecs_os_api_init_t init_
init callback.
Definition os_api.h:321
ecs_os_api_get_time_t get_time_
get_time callback.
Definition os_api.h:365
ecs_os_api_cond_broadcast_t cond_broadcast_
cond_broadcast callback.
Definition os_api.h:358
ecs_os_api_calloc_t calloc_
calloc callback.
Definition os_api.h:327
ecs_os_api_dlopen_t dlopen_
dlopen callback.
Definition os_api.h:380
ecs_os_api_perf_trace_t perf_trace_push_
perf_trace_push callback.
Definition os_api.h:402
ecs_os_api_thread_self_t thread_self_
thread_self callback.
Definition os_api.h:336
ecs_os_api_fclose_t fclose_
fclose callback.
Definition os_api.h:394
ecs_os_api_fread_t fread_
fread callback.
Definition os_api.h:395
ecs_os_api_thread_join_t thread_join_
thread_join callback.
Definition os_api.h:335
ecs_os_api_module_to_path_t module_to_dl_
module_to_dl callback.
Definition os_api.h:386
ecs_os_api_remove_t remove_
remove callback.
Definition os_api.h:399
int32_t log_indent_
Tracing indentation level.
Definition os_api.h:406
ecs_os_api_malloc_t malloc_
malloc callback.
Definition os_api.h:325
ecs_os_api_log_t log_
log callback.
Definition os_api.h:368
ecs_os_api_thread_join_t task_join_
task_join callback.
Definition os_api.h:340
int64_t log_last_timestamp_
Last logged timestamp.
Definition os_api.h:408
ecs_os_api_mutex_new_t mutex_new_
mutex_new callback.
Definition os_api.h:349
ecs_os_api_lainc_t ladec_
ladec callback.
Definition os_api.h:346
void * log_out_
File used for logging output (type is FILE*) (hint: log_ decides where to write).
Definition os_api.h:412
ecs_os_api_cond_new_t cond_new_
cond_new callback.
Definition os_api.h:355
ecs_os_api_perf_trace_t perf_trace_pop_
perf_trace_pop callback.
Definition os_api.h:403
ecs_os_api_thread_new_t task_new_
task_new callback.
Definition os_api.h:339
int32_t log_level_
Tracing level.
Definition os_api.h:405
ecs_os_api_fini_t fini_
fini callback.
Definition os_api.h:322
ecs_os_api_remove_t rmdir_
rmdir callback.
Definition os_api.h:398
ecs_os_api_cond_signal_t cond_signal_
cond_signal callback.
Definition os_api.h:357
ecs_os_api_cond_free_t cond_free_
cond_free callback.
Definition os_api.h:356
ecs_os_api_strdup_t strdup_
strdup callback.
Definition os_api.h:331
ecs_os_api_mutex_free_t mutex_free_
mutex_free callback.
Definition os_api.h:350
ecs_os_api_module_to_path_t module_to_etc_
module_to_etc callback.
Definition os_api.h:390
ecs_flags32_t flags_
OS API flags.
Definition os_api.h:410
ecs_os_api_now_t now_
now callback.
Definition os_api.h:364
ecs_os_api_mutex_lock_t mutex_lock_
mutex_lock callback.
Definition os_api.h:351
ecs_os_api_ainc_t ainc_
ainc callback.
Definition os_api.h:343
ecs_os_api_ainc_t adec_
adec callback.
Definition os_api.h:344
ecs_os_api_dlproc_t dlproc_
dlproc callback.
Definition os_api.h:381
ecs_os_api_fwrite_t fwrite_
fwrite callback.
Definition os_api.h:396
ecs_os_api_dlclose_t dlclose_
dlclose callback.
Definition os_api.h:382
Time type.
Definition os_api.h:39
uint32_t sec
Second part.
Definition os_api.h:40
uint32_t nanosec
Nanosecond part.
Definition os_api.h:41