Next: 4.10 Classes Up: 4. The libonyx library Previous: 4.8 Guidelines for writing Contents Index

# 4.9 API

void libonyx_init(int a_argc, char **a_argv, char **a_envp):

  Input(s):
    a_argc:
      Number of command line arguments.
    a_argv:
      Pointer to an array of command line argument strings.
    a_envp:
      Pointer to an array of environment variable strings.
  Output(s):
    None.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Initialize various global state.

void libonyx_shutdown(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Clean up the global variables that are initialized by libonyx_init().

cw_nxo_t * libonyx_argv_get(void):

  Input(s):
    None.
  Output(s):
    retval:
      Pointer to the nxo corresponding to argv .
  Exception(s):
    None.
  Description:
    Return a pointer to the nxo corresponding to argv .

cw_nxo_t * libonyx_envdict_get(void):

  Input(s):
    None.
  Output(s):
    retval:
      Pointer to the nxo corresponding to envdict .
  Exception(s):
    None.
  Description:
    Return a pointer to the nxo corresponding to envdict .

cw_nxo_t * libonyx_gcdict_get(void):

  Input(s):
    None.
  Output(s):
    retval:
      Pointer to the nxo corresponding to gcdict .
  Exception(s):
    None.
  Description:
    Return a pointer to the nxo corresponding to gcdict .

void * cw_opaque_alloc_t(void *a_arg, size_t a_size, const char *a_filename, uint32_t a_line_num):

  Input(s):
    a_arg:
      Opaque pointer.
    a_size:
      Size of memory range to allocate.
    a_filename:
      Should be __FILE__.
    a_line_num:
      Should be __LINE__.
  Output(s):
    retval:
      Pointer to a memory range.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Allocate a_size of space and return a pointer to it.

void * cw_opaque_calloc_t(void *a_arg, size_t a_number, size_t a_size, const char *a_filename, uint32_t a_line_num):

  Input(s):
    a_arg:
      Opaque pointer.
    a_number:
      Number of elements to allocate.
    a_size:
      Size of each element to allocate.
    a_filename:
      Should be __FILE__.
    a_line_num:
      Should be __LINE__.
  Output(s):
    retval:
      Pointer to a zeroed memory range.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Allocate a zeroed array of a_number objects, each a_size bytes long, and return a pointer to the array.

void * cw_opaque_realloc_t(void *a_arg, void *a_ptr, size_t a_size, size_t a_old_size, const char *a_filename, uint32_t a_line_num):

  Input(s):
    a_arg:
      Opaque pointer.
    a_ptr:
      Pointer to memory range to be reallocated.
    a_size:
      Size of memory range to allocate.
    a_old_size:
      Size of memory range previously pointed to by a_ptr.
    a_filename:
      Should be __FILE__.
    a_line_num:
      Should be __LINE__.
  Output(s):
    retval:
      Pointer to a memory range.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Reallocate a_size of space and return a pointer to it.

void cw_opaque_dealloc_t(void *a_mem, void *a_ptr, size_t a_size, const char *a_filename, uint32_t a_line_num):

  Input(s):
    a_arg:
      Opaque pointer.
    a_ptr:
      Pointer to to memory range to be freed.
    a_size:
      Sizef of memory range pointed to by a_ptr.
    a_filename:
      Should be __FILE__.
    a_line_num:
      Should be __LINE__.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Deallocate the memory pointed to by a_ptr.

void * cw_opaque_alloc(cw_opaque_alloc_t *a_func, void *a_arg, size_t a_size):

  Input(s):
    a_func:
      Opaque allocator function pointer.
    a_arg:
      Opaque pointer.
    a_size:
      Size of memory range to allocate.
  Output(s):
    retval:
      Pointer to a memory range.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Allocate a_size of space and return a pointer to it.

void * cw_opaque_calloc(cw_opaque_calloc_t *a_func, void *a_arg, size_t a_number, size_t a_size):

  Input(s):
    a_func:
      Opaque allocator function pointer.
    a_arg:
      Opaque pointer.
    a_number:
      Number of elements to allocate.
    a_size:
      Size of each element to allocate.
  Output(s):
    retval:
      Pointer to a zeroed memory range.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Allocate a zeroed array of a_number objects, each a_size bytes long, and return a pointer to the array.

void * cw_opaque_realloc(cw_opaque_realloc_t *a_func, void *a_arg, void *a_ptr, size_t a_size, size_t a_old_size):

  Input(s):
    a_func:
      Opaque allocator function pointer.
    a_arg:
      Opaque pointer.
    a_ptr:
      Pointer to memory range to be reallocated.
    a_size:
      Size of memory range to allocate.
    a_old_size:
      Size of memory range previously pointed to by a_ptr.
  Output(s):
    retval:
      Pointer to a memory range.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Reallocate a_size of space and return a pointer to it.

void cw_opaque_dealloc(cw_opaque_dealloc_t *a_func, void *a_mem, void *a_ptr, size_t a_size):

  Input(s):
    a_func:
      Opaque allocator function pointer.
    a_arg:
      Opaque pointer.
    a_ptr:
      Pointer to to memory range to be freed.
    a_size:
      Sizef of memory range pointed to by a_ptr.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Deallocate the memory pointed to by a_ptr.

void cw_onyx_code(cw_nxo_t *a_thread, const char *a_code):

  Input(s):
    a_thread:
      Pointer to a thread nxo.
    a_code:
      A "-delimited string constant.
  Output(s):
    None.
  Exception(s):
    Depends on actions of a_code.
  Description:
    Convenience macro for static embedded Onyx code.

void cw_assert(expression):

  Input(s):
    expression:
      C expression that evaluates to zero or non-zero.
  Output(s):
    Possible error printed to stderr.
  Exception(s):
    None.
  Description:
    If the expression evaluates to zero, print an error message to stderr and abort().

    Note: This macro is only active if the CW_ASSERT cpp macro is defined.

void cw_dassert(expression):

  Input(s):
    expression:
      C expression that evaluates to zero or non-zero.
  Output(s):
    Possible error printed to stderr.
  Exception(s):
    None.
  Description:
    If the expression evaluates to zero, print an error message to stderr and abort().

    Note: This macro is only active if the CW_ASSERT and CW_DBG cpp macros are defined.

void cw_not_reached(void):

  Input(s):
    None.
  Output(s):
    Error printed to stderr.
  Exception(s):
    None.
  Description:
    Abort with an error message.

    Note: This macro is only active if the CW_ASSERT cpp macro is defined.

void cw_check_ptr(a_pointer):

  Input(s):
    a_pointer:
      A pointer.
  Output(s):
    Possible error printed to stderr.
  Exception(s):
    None.
  Description:
    If a_pointer is NULL, print an error message to stderr and abort().

    Note: This macro is only active if the CW_ASSERT cpp macro is defined.

void cw_error(const char *a_str):

  Input(s):
    a_str:
      Pointer to a NULL-terminated character array.
  Output(s):
    Contents of a_str, followed by a carriage return, printed to stderr.
  Exception(s):
    None.
  Description:
    Print the contents of a_str, followed by a carriage return, to stderr.

uint64_t cw_ntohq(uint64_t a_val):

  Input(s):
    a_val:
      64 bit integer.
  Output(s):
    retval:
      64 bit integer.
  Exception(s):
    None.
  Description:
    Convert a_val from network byte order to host byte order and return the result.

uint64_t cw_htonq(uint64_t a_val):

  Input(s):
    a_val:
      64 bit integer.
  Output(s):
    retval:
      64 bit integer.
  Exception(s):
    None.
  Description:
    Convert a_val from host byte order to network byte order and return the result.

uint32_t cw_offsetof(<type> a_type, <field_name> a_field):

  Input(s):
    a_type:
      C structure type name.
    a_field:
      Name of a field within a_type.
  Output(s):
    retval:
      Offset of a_field into a_type.
  Exception(s):
    None.
  Description:
    Calculate the offset of a_field into a_type and return the result.

Next: 4.10 Classes Up: 4. The libonyx library Previous: 4.8 Guidelines for writing Contents Index