sys.h

Include dependency graph for sys.h:

This graph shows which files directly or indirectly include sys.h:

Platform specific functions.

This header defines platform dependent functions, that mostly deals with events. Some functions can be implemented by using functions defined and implemented in listeners.h header.

Typedefs

typedef struct EventListener EventListener

Event listener.

An event listener structure should be defined by the platform. Event listeners belong to the GlobalContext.listeners synchronized list.

typedef EventListener *(*event_handler_t)(GlobalContext *glb, EventListener *listener)

Event handlers (for ports)

The event handler is called from the scheduler thread but outside any process. It can send messages to processes using globalcontext_send_message function.

Result of this callback alters the list of handlers which is locked for writing when it is called. It can:

• return listener, in which case the list is not modified

• return NULL, in which case the entry is removed. The callback is responsible for freeing the listener.

• return another listener, in which case the current listener is replaced by the other listener. The callback is responsible for freeing the previous listener if it is no longer needed.

Appending a listener is also possible by altering the list head.

This callback is defined for platforms using listeners.h header and can be ignored by others.

Param glb:

global context

Param listener:

the current listener

Return:

NULL if the current listener should be removed, listener if it should be kept or another listener if it should be replaced.

Enums

enum [anonymous]

Values:

enumerator SYS_POLL_EVENTS_DO_NOT_WAIT = 0

enumerator SYS_POLL_EVENTS_WAIT_FOREVER = -1

enum OpenAVMResult

Values:

enumerator AVM_OPEN_OK = 0

enumerator AVM_OPEN_FAILED_ALLOC = 1

enumerator AVM_OPEN_INVALID = 2

enumerator AVM_OPEN_CANNOT_OPEN = 3

enumerator AVM_OPEN_CANNOT_READ = 4

enumerator AVM_OPEN_NOT_SUPPORTED = 5

Functions

void sys_poll_events(GlobalContext *glb, int timeout_ms)

Poll events (from drivers and select events), with a timeout (in ms), or until sys_signal is called.

Depending on platforms, check all open file descriptors/queues and call drivers that should send messages to contexts (which will unblock them). With SMP builds, this function can be called from any scheduler.

If selectable events are supported on the platform, this function should also:

• call select_event_destroy on select events that have close set to 1

• include the set of ErlNifEvent that are marked for read or write in the select set, and if they are selected, call select_event_notify to send the notification.

select_event_count_and_destroy_closed defined in resources.h can be used to process closed select events.

Parameters:

• glb – the global context.

• timeout_ms – the number of ms to wait, SYS_POLL_EVENTS_WAIT_FOREVER to wait forever.

void sys_register_select_event(GlobalContext *glb, ErlNifEvent event, bool is_write)

Update the select set by adding an event for reading or writing.

This function probably should update set and call sys_signal so new set is taken into account.

Parameters:

• glb – the global context.

• event – the event (file descriptor) to add to the set

• is_write – whether to add the event for writing (as opposed to reading)

void sys_unregister_select_event(GlobalContext *glb, ErlNifEvent event, bool is_write)

Update the select set by removing an event for reading or writing.

This function probably should update set and call sys_signal so new set is taken into account. After this function is called, sys_poll_events must check for closed select events.

Parameters:

• glb – the global context.

• event – the event (file descriptor) to remove from the set

• is_write – whether to remove the event for writing (as opposed to reading)

void sys_register_listener(GlobalContext *global, EventListener *listener)

Register a listener.

This function is called by ports to register a listener which is a native alternative to select events. The actual definition of listeners is platform dependent.

Parameters:

• global – the global context.

• listener – the listener to register

void sys_unregister_listener(GlobalContext *global, EventListener *listener)

Unregister a listener.

This function is called by ports to unregister a listener which is a native alternative to select events. The actual definition of listeners is platform dependent.

Parameters:

• global – the global context.

• listener – the listener to unregister.

void sys_listener_destroy(struct ListHead *item)

Free a listener.

This function is called when the global context is destroyed on every remaining listener. An implementation is available in listeners.h.

Parameters:

• item – list item

void sys_signal(GlobalContext *glb)

Interrupt the wait in sys_poll_events.

This function should signal the thread that is waiting in sys_poll_events so it returns before the timeout. It is mostly used for SMP builds, but also to abort sleep from driver callbacks on FreeRTOS.

Please note that this function may be called while no thread is waiting in sys_poll_events and this should have no effect. This function is called in scheduler loop (internal function scheduler_run0) and when scheduling processes.

Parameters:

• glb – the global context.

enum OpenAVMResult sys_open_avm_from_file(GlobalContext *global, const char *path, struct AVMPackData **data)

void sys_time(struct timespec *t)

gets wall clock time

gets system wall clock time, used by erlang:system_time/1

Parameters:

• t – the timespec that will be updated.

void sys_monotonic_time(struct timespec *t)

gets monotonic time

gets the time that is used by erlang:monotonic_time/1

Parameters:

• t – the timespec that will be updated.

uint64_t sys_monotonic_time_u64()

gets monotonic time for timers

This function must return a non-overflowing counter in the highest precision the platform permits to make sure that we don’t have truncation errors when compared with sys_time or sys_monotonic_time. Returning the number of microseconds or nanoseconds since boot would work.

Returns:

a monotonic time in a system-chosen unit

uint64_t sys_monotonic_time_ms_to_u64(uint64_t ms)

convert a number of milliseconds to system-chosen unit

Parameters:

• ms – the number of milliseconds to convert

Returns:

the result of the conversion

uint64_t sys_monotonic_time_u64_to_ms(uint64_t t)

convert a number in system-chosen unit to milliseconds

Parameters:

• t – the number to convert

Returns:

the result of the conversion

Module *sys_load_module(GlobalContext *global, const char *module_name)

Loads a BEAM module using platform dependent methods.

Loads a BEAM module into memory using platform dependent methods and returns a pointer to a Module struct.

Parameters:

• global – the global context.

• module_name – the name of the BEAM file (e.g. “mymodule.beam”).

Module *sys_load_module_from_file(GlobalContext *global, const char *path)

Context *sys_create_port(GlobalContext *glb, const char *driver_name, term opts)

Create a port driver.

This function creates a port driver, encapsulated in a Context object. This function should create a Context object through the supplied global context, which will assume ownership of the new instance.

Parameters:

• glb – the global context.

• driver_name – the name of the driver that will control the port.

• opts – the term options passed into the port open command.

Returns:

a new Context instance, or NULL, if a driver cannot be created from the inputs.

term sys_get_info(Context *ctx, term key)

Get platform-dependent information for the specified key.

This function returns platform-dependent information specified by the supplied key. If not information is available for the specified key, this function should return the atom ‘undefined’

Parameters:

• ctx – the current context

• key – an atom used to indicate the type of information requested.

Returns:

a term containing the requested information, or the atom undefined, if there is no system information for the specified key.

void sys_init_platform(GlobalContext *global)

Initialize the platform, setting global->platform_data.

void sys_free_platform(GlobalContext *global)

Free the platform data structure.

Cleanup the platform data structure. Called by global_context_destroy.