R API

The Safe Runtime (R) is a portable runtime library for embedded applications.

The R library provides management for binary searching, buffering, error handling, events, events, files, hashing, lists, logging, memory, ssl, sockets, strings, and date/time functions. It also provides a foundation of safe routines for secure programming, that help to prevent buffer overflows and other security threats. The library can be used in both C and C++ programs.

The R library uses a set extended typedefs for common types. These include: bool, cchar, cvoid, uchar, short, ushort, int, uint, long, ulong, int32, uint32, int64, uint64, float, and double. The cchar type is a const char, cvoid is const void. Several types have "u" prefixes to denote unsigned qualifiers.

The library includes a memory allocator and global memory allocation handler.

The library provides support for fiber coroutines to enable parallel programming without callbacks or complex threads. The network APIs use fibers to transparently block the fiber and resume other fibers automatically. This enables a straight-line "blocking" programming paradigm while enabling other fibers to run as required.

Extensions

Functions

PUBLIC void	assert(bool cond)
	Asser that a condition is true.
PUBLIC void,*	rAlloc(size_t size)
	Allocate a block of memory.
PUBLIC void	rAllocException(int cause, size_t size)
	Signal a memory allocation exception.
PUBLIC void,*	rAllocType(RType type)
	Allocate an object of a given type.
PUBLIC void	rBreakpoint(void)
	Trigger a breakpoint.
PUBLIC int	rDaemonize(void)
	For the current process and run as a daemon.
PUBLIC ssize	rFprintf(FILE fp, cchar fmt, ...)
	Formatted print to the standard error channel.
PUBLIC void	rFree(void *ptr)
	Free a block of memory allocated via rAlloc.
PUBLIC cchar,*	rGetAppName(void)
	Get the application name defined via rSetAppName.
PUBLIC cchar,*	rGetError(int error)
	Return a string representation of an R error code.
PUBLIC int	rGetOsError(void)
	Return the native O/S error code.
PUBLIC cchar,*	rGetServerName(void)
	Get the application server name string.
PUBLIC int	rGetState(void)
	Get the current R state.
PUBLIC bool	rGetTimeouts(void)
	Return true if timeouts are enabled.
PUBLIC void	rGracefulStop(void)
	Gracefully stop the app.
PUBLIC int	rInit(RFiberProc fn, cvoid *arg)
	Initialize the runtime.
PUBLIC int	rInitOs(void)
	Create and initialze the O/S dependent subsystem.
PUBLIC void,*	rMemdup(cvoid *ptr, size_t size)
	Duplicate a block of memory.
PUBLIC ssize	rPrintf(cchar *fmt, ...)
	Formatted print.
PUBLIC void,*	rRealloc(void *ptr, size_t size)
	Allocate a block of memory.
PUBLIC void	rSetMemHandler(RMemProc handler)
	Define a global memory exhaustion handler.
PUBLIC void	rSetOsError(int error)
	Set the O/S error code.
PUBLIC void	rSetState(int state)
	Set the R state.
PUBLIC void	rSetTimeouts(bool on)
	Control timeouts.
PUBLIC void	rSleep(Ticks ticks)
	Sleep a fiber for the requested number of milliseconds.
PUBLIC char,*	rSnprintf(char buf, ssize maxsize, cchar fmt, ...)
	Format a string into a buffer.
PUBLIC void	rStop(void)
	Immediately stop the app.
PUBLIC void	rTermOs(void)
	Stop the O/S dependent subsystem.
PUBLIC char,*	rVsnprintf(char buf, ssize maxsize, cchar fmt, va_list args)
	Format a string into a buffer.
PUBLIC int	rWritePid(void)
	Write the current process pid to /var/run.

Typedefs

RFiberProc	Fiber entry point function.
RMemProc	Memory exhaustion callback procedure.
Socket	Argument for sockets.
size_t	Unsigned integral type.
time_t	Unsigned time type.

Defines

#define	R_MEM_FAIL 0x4
	Memory allocation failed - immediate exit.
#define	R_MEM_LIMIT 0x2
	Memory use exceeds memory limit - invoking policy.
#define	R_MEM_STACK 0x10
	Too many fiber stack.
#define	R_MEM_TOO_BIG 0x8
	Memory allocation request is too big - immediate exit.
#define	R_MEM_WARNING 0x1
	Memory use exceeds warnHeap level limit.

Functions

PUBLIC void void assert (bool cond)

Asser that a condition is true.

Parameters:

cond	Boolean result of a conditional test.

API Stability:: Evolving.

PUBLIC void,* void * rAlloc (size_t size)

Allocate a block of memory.

Description:: This is the lowest level of memory allocation routine. Memory is freed via rFree.

Parameters:

size	Size of the memory block to allocate.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler will be invoked.

Remarks:: Do not mix calls to rAlloc and malloc.

API Stability:: Evolving.

PUBLIC void void rAllocException (int cause, size_t size)

Signal a memory allocation exception.

Description:: R uses a global memory allocaction error handler. If doing direct malloc() allocations that fail, call this routine to signal the memory failure and run the allocation handler.

Parameters:

cause	Set to R_MEM_WARNING, R_MEM_LIMIT, R_MEM_FAIL or R_MEM_TO_BIG.
size	Size in bytes of the failing allocation.

API Stability:: Evolving.

PUBLIC void,* void * rAllocType (RType type)

Allocate an object of a given type.

Description:: Allocates a zeroed block of memory large enough to hold an instance of the specified type.

Parameters:

type	RType of the object to allocate.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory allocation handler will be invoked.

API Stability:: Evolving.

PUBLIC void void rBreakpoint (void )

Trigger a breakpoint.

Description:: This routine is invoked for asserion errors from rAssert and errors from rError. It is useful in debuggers as breakpoint location for detecting errors.

API Stability:: Evolving.

PUBLIC int int rDaemonize (void )

For the current process and run as a daemon.

API Stability:: Evolving.

PUBLIC ssize ssize rFprintf (FILE *fp, cchar *fmt, ...)

Formatted print to the standard error channel.

Description:: This is a secure replacement for fprintf. It can handle null arguments without crashes.

Parameters:

fp	File handle.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Evolving.

PUBLIC void void rFree (void *ptr)

Free a block of memory allocated via rAlloc.

Description:: This releases a block of memory allocated via rAllocMem.

Parameters:

ptr	Pointer to the block. If ptr is null, the call is skipped.

Remarks:: The rFree routine is a macro over rFreeMem. Do not mix calls to rFreeMem and free.

API Stability:: Evolving.

PUBLIC cchar,* cchar * rGetAppName (void )

Get the application name defined via rSetAppName.

Returns:: The one-word lower case application name defined via rSetAppName.

API Stability:: Evolving.

PUBLIC cchar,* cchar * rGetError (int error)

Return a string representation of an R error code.

Parameters:

error

An R error code. These codes are always negative for errors and zero for R_OK.

Returns:: A static string error representation.

API Stability:: Evolving.

PUBLIC int int rGetOsError (void )

Return the native O/S error code.

Description:: Returns an O/S error code from the most recent system call. This returns errno on Unix systems or GetLastError() on Windows.

Returns:: The O/S error code.

API Stability:: Evolving.

PUBLIC cchar,* cchar * rGetServerName (void )

Get the application server name string.

Returns:: A string containing the application server name string.

API Stability:: Evolving.

PUBLIC int int rGetState (void )

Get the current R state.

Returns:: Returns R_INITIALIZED, R_READY, R_STOPPING or R_STOPPED.

API Stability:: Evolving.

PUBLIC bool bool rGetTimeouts (void )

Return true if timeouts are enabled.

Returns:: True if timeouts are enabled.

API Stability:: Evolving.

PUBLIC void void rGracefulStop (void )

Gracefully stop the app.

Description:: Queued events will be serviced.

API Stability:: Evolving.

PUBLIC int int rInit (RFiberProc fn, cvoid *arg)

Initialize the runtime.

Description:: This routine should be called at startup from main().

Parameters:

fn	Fiber function to start.
arg	Argument to the fiber function.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC int int rInitOs (void )

Create and initialze the O/S dependent subsystem.

Description:: Called internally by the RT. Should not be called by users.

API Stability:: Internal.

PUBLIC void,* void * rMemdup (cvoid *ptr, size_t size)

Duplicate a block of memory.

Description:: Copy a block of memory into a newly allocated block.

Parameters:

ptr	Pointer to the block to duplicate.
size	Size of the block to copy.

Returns:: Returns an allocated block.

API Stability:: Evolving.

PUBLIC ssize ssize rPrintf (cchar *fmt, ...)

Formatted print.

This is a secure verion of printf that can handle null args

Description:: This is a secure replacement for printf. It can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Evolving.

PUBLIC void,* void * rRealloc (void *ptr, size_t size)

Allocate a block of memory.

Description:: This is the lowest level of memory allocation routine. Memory is freed via rFree.

Parameters:

size	Size of the memory block to allocate.
ptr	Pointer to the block. If ptr is null, the call is skipped.

Returns:: Returns a pointer to the reallocated block. If memory is not available the memory exhaustion handler will be invoked.

Remarks:: Do not mix calls to rRealloc and malloc.

API Stability:: Evolving.

PUBLIC void void rSetMemHandler (RMemProc handler)

Define a global memory exhaustion handler.

Description:: The memory handler will be invoked for memory allocation errors.

Parameters:

handler

Callback function invoked with the signature: void fn(int cause, size_t size).

API Stability:: Evolving.

PUBLIC void void rSetOsError (int error)

Set the O/S error code.

Description:: Set errno or equivalent.

API Stability:: Evolving.

PUBLIC void void rSetState (int state)

Set the R state.

Description:: This API is thread safe and can be called from a foreign thread.

Parameters:

state

Set to R_INITIALIZED, R_READY, R_STOPPING or R_STOPPED.

API Stability:: Evolving.

PUBLIC void void rSetTimeouts (bool on)

Control timeouts.

Parameters:

on	Set to false to disable timeouts for debugging.

API Stability:: Evolving.

PUBLIC void void rSleep (Ticks ticks)

Sleep a fiber for the requested number of milliseconds.

: Must be called from a fiber.

Description:: Pause a fiber for the requested duration and then resume via the main fiber. Other fibers continue to run.

Parameters:

ticks

Time period in milliseconds to sleep.

API Stability:: Evolving.

PUBLIC char,* char * rSnprintf (char *buf, ssize maxsize, cchar *fmt, ...)

Format a string into a buffer.

Description:: This routine will format the arguments into a result. If a buffer is supplied, it will be used. Otherwise if the buf argument is NULL, a buffer will be allocated. The arguments will be formatted up to the maximum size supplied by the maxsize argument. A trailing NULL will always be appended.

Parameters:

buf	Optional buffer to contain the formatted result.
maxsize	Maximum size of the result.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The original buffer if supplied or else an allocated string.

API Stability:: Prototype.

PUBLIC void void rStop (void )

Immediately stop the app.

Description:: This API is thread safe and can be called from a foreign thread.

Description:: Queued events will not be serviced.

API Stability:: Evolving.

PUBLIC void void rTermOs (void )

Stop the O/S dependent subsystem.

API Stability:: Internal.

PUBLIC char,* char * rVsnprintf (char *buf, ssize maxsize, cchar *fmt, va_list args)

Format a string into a buffer.

Description:: This routine will format the arguments into a result. If a buffer is supplied, it will be used. Otherwise if the buf argument is NULL, a buffer will be allocated. The arguments will be formatted up to the maximum size supplied by the maxsize argument. A trailing NULL will always be appended.

Parameters:

buf	Optional buffer to contain the formatted result.
maxsize	Maximum size of the result.
fmt	Printf style format string.
args	Variable arguments to format.

Returns:: The original buffer if supplied or else an allocated string.

API Stability:: Prototype.

PUBLIC int int rWritePid (void )

Write the current process pid to /var/run.

Returns:: Zero on success, otherwise a negative status code.

Typedefs

typedef void(* RFiberProc) (void *data).

Fiber entry point function.

Parameters:

data	Custom function argument.

API Stability:: Evolving.

typedef void(* RMemProc) (int cause, size_t size).

Memory exhaustion callback procedure.

Parameters:

cause	The cause of the memory failure.
size	The size of the failing block allocation.

typedef long size_t.

Unsigned integral type.

Equivalent in size to void*

typedef int Socket.

Argument for sockets.

typedef unsigned long time_t.

Unsigned time type.

Time in seconds since Jan 1, 1970