erl_driver: Api functions for an erlang driver

DESCRIPTION

An Erlang driver is a library containing a set of native driver callback functions that the Erlang VM calls when certain events occur. There may be multiple instances of a driver, each instance is associated with an Erlang port.

Warning:

Use this functionality with extreme care!

A driver callback is executed as a direct extension of the native code of the VM. Execution is not made in a safe environment. The VM can not provide the same services as provided when executing Erlang code, such as preemptive scheduling or memory protection. If the driver callback function doesn't behave well, the whole VM will misbehave.

*: A driver callback that crash will crash the whole VM.

*: An erroneously implemented driver callback might cause a VM internal state inconsistency which may cause a crash of the VM, or miscellaneous misbehaviors of the VM at any point after the call to the driver callback.

*: A driver callback that do lengthy work before returning will degrade responsiveness of the VM, and may cause miscellaneous strange behaviors. Such strange behaviors include, but are not limited to, extreme memory usage, and bad load balancing between schedulers. Strange behaviors that might occur due to lengthy work may also vary between OTP releases.

As of erts version 5.5.3 the driver interface has been extended (see extended marker). The extended interface introduce version management, the possibility to pass capability flags (see driver flags) to the runtime system at driver initialization, and some new driver API functions.

Note:

As of erts version 5.9 old drivers have to be recompiled and have to use the extended interface. They also have to be adjusted to the 64-bit capable driver interface.

The driver calls back to the emulator, using the API functions declared in erl_driver.h. They are used for outputting data from the driver, using timers, etc.

Each driver instance is associated with a port. Every port has a port owner process. Communication with the port is normally done through the port owner process. Most of the functions take the port handle as an argument. This identifies the driver instance. Note that this port handle must be stored by the driver, it is not given when the driver is called from the emulator (see driver_entry).

Some of the functions take a parameter of type ErlDrvBinary, a driver binary. It should be both allocated and freed by the caller. Using a binary directly avoids one extra copying of data.

Many of the output functions have a "header buffer", with hbuf and hlen parameters. This buffer is sent as a list before the binary (or list, depending on port mode) that is sent. This is convenient when matching on messages received from the port. (Although in the latest versions of Erlang, there is the binary syntax, that enables you to match on the beginning of a binary.)

In the runtime system with SMP support, drivers are locked either on driver level or port level (driver instance level). By default driver level locking will be used, i.e., only one emulator thread will execute code in the driver at a time. If port level locking is used, multiple emulator threads may execute code in the driver at the same time. There will only be one thread at a time calling driver call-backs corresponding to the same port, though. In order to enable port level locking set the ERL_DRV_FLAG_USE_PORT_LOCKING driver flag in the driver_entry used by the driver. When port level locking is used it is the responsibility of the driver writer to synchronize all accesses to data shared by the ports (driver instances).

Most drivers written before the runtime system with SMP support existed will be able to run in the runtime system with SMP support without being rewritten if driver level locking is used.

Note:

It is assumed that drivers do not access other drivers. If drivers should access each other they have to provide their own mechanism for thread safe synchronization. Such "inter driver communication" is strongly discouraged.

Previously, in the runtime system without SMP support, specific driver call-backs were always called from the same thread. This is not the case in the runtime system with SMP support. Regardless of locking scheme used, calls to driver call-backs may be made from different threads, e.g., two consecutive calls to exactly the same call-back for exactly the same port may be made from two different threads. This will for most drivers not be a problem, but it might. Drivers that depend on all call-backs being called in the same thread, have to be rewritten before being used in the runtime system with SMP support.

Note:

Regardless of locking scheme used, calls to driver call-backs may be made from different threads.

Most functions in this API are not thread-safe, i.e., they may not be called from an arbitrary thread. Functions that are not documented as thread-safe may only be called from driver call-backs or function calls descending from a driver call-back call. Note that driver call-backs may be called from different threads. This, however, is not a problem for any function in this API, since the emulator has control over these threads.

Warning:

Functions not explicitly documented as thread safe are not thread safe. Also note that some functions are only thread safe when used in a runtime system with SMP support.

A function not explicitly documented as thread safe may at some point in time have a thread safe implementation in the runtime system. Such an implementation may however change to a thread unsafe implementation at any time without any notice at all.

Only use functions explicitly documented as thread safe from arbitrary threads.

As mentioned in the warning text at the beginning of this document it is of vital importance that a driver callback does return relatively fast. It is hard to give an exact maximum amount of time that a driver callback is allowed to work, but as a rule of thumb a well behaving driver callback should return before a millisecond has passed. This can be achieved using different approaches. If you have full control over the code that are to execute in the driver callback, the best approach is to divide the work into multiple chunks of work and trigger multiple calls to the timeout callback using zero timeouts. The erl_drv_consume_timeslice() function can be useful in order to determine when to trigger such timeout callback calls. It might, however, not always be possible to implement it this way, e.g. when calling third party libraries. In this case you typically want to dispatch the work to another thread. Information about thread primitives can be found below.

FUNCTIONALITY

All functions that a driver needs to do with Erlang are performed through driver API functions. There are functions for the following functionality:

Timer functions: Timer functions are used to control the timer that a driver may use. The timer will have the emulator call the timeout entry function after a specified time. Only one timer is available for each driver instance.

Queue handling: Every driver instance has an associated queue. This queue is a SysIOVec that works as a buffer. It's mostly used for the driver to buffer data that should be written to a device, it is a byte stream. If the port owner process closes the driver, and the queue is not empty, the driver will not be closed. This enables the driver to flush its buffers before closing.

The queue can be manipulated from arbitrary threads if a port data lock is used. See documentation of the ErlDrvPDL type for more information.

Output functions: With the output functions, the driver sends data back to the emulator. They will be received as messages by the port owner process, see open_port/2. The vector function and the function taking a driver binary are faster, because they avoid copying the data buffer. There is also a fast way of sending terms from the driver, without going through the binary term format.

Failure: The driver can exit and signal errors up to Erlang. This is only for severe errors, when the driver can't possibly keep open.

Asynchronous calls: The latest Erlang versions (R7B and later) has provision for asynchronous function calls, using a thread pool provided by Erlang. There is also a select call, that can be used for asynchronous drivers.

Multi-threading: A POSIX thread like API for multi-threading is provided. The Erlang driver thread API only provide a subset of the functionality provided by the POSIX thread API. The subset provided is more or less the basic functionality needed for multi-threaded programming:

*: Threads

*: Mutexes

*: Condition variables

*: Read/Write locks

*: Thread specific data

The Erlang driver thread API can be used in conjunction with the POSIX thread API on UN-ices and with the Windows native thread API on Windows. The Erlang driver thread API has the advantage of being portable, but there might exist situations where you want to use functionality from the POSIX thread API or the Windows native thread API.

The Erlang driver thread API only returns error codes when it is reasonable to recover from an error condition. If it isn't reasonable to recover from an error condition, the whole runtime system is terminated. For example, if a create mutex operation fails, an error code is returned, but if a lock operation on a mutex fails, the whole runtime system is terminated.

Note that there exists no "condition variable wait with timeout" in the Erlang driver thread API. This is due to issues with pthread_cond_timedwait(). When the system clock suddenly is changed, it isn't always guaranteed that you will wake up from the call as expected. An Erlang runtime system has to be able to cope with sudden changes of the system clock. Therefore, we have omitted it from the Erlang driver thread API. In the Erlang driver case, timeouts can and should be handled with the timer functionality of the Erlang driver API.

In order for the Erlang driver thread API to function, thread support has to be enabled in the runtime system. An Erlang driver can check if thread support is enabled by use of driver_system_info(). Note that some functions in the Erlang driver API are thread-safe only when the runtime system has SMP support, also this information can be retrieved via driver_system_info(). Also note that a lot of functions in the Erlang driver API are not thread-safe regardless of whether SMP support is enabled or not. If a function isn't documented as thread-safe it is not thread-safe.

NOTE: When executing in an emulator thread, it is very important that you unlock all locks you have locked before letting the thread out of your control; otherwise, you are very likely to deadlock the whole emulator. If you need to use thread specific data in an emulator thread, only have the thread specific data set while the thread is under your control, and clear the thread specific data before you let the thread out of your control.

In the future there will probably be debug functionality integrated with the Erlang driver thread API. All functions that create entities take a name argument. Currently the name argument is unused, but it will be used when the debug functionality has been implemented. If you name all entities created well, the debug functionality will be able to give you better error reports.

Adding / removing drivers: A driver can add and later remove drivers.

Monitoring processes: A driver can monitor a process that does not own a port.

Version management: Version management is enabled for drivers that have set the extended_marker field of their driver_entry to ERL_DRV_EXTENDED_MARKER. erl_driver.h defines ERL_DRV_EXTENDED_MARKER, ERL_DRV_EXTENDED_MAJOR_VERSION, and ERL_DRV_EXTENDED_MINOR_VERSION. ERL_DRV_EXTENDED_MAJOR_VERSION will be incremented when driver incompatible changes are made to the Erlang runtime system. Normally it will suffice to recompile drivers when the ERL_DRV_EXTENDED_MAJOR_VERSION has changed, but it could, under rare circumstances, mean that drivers have to be slightly modified. If so, this will of course be documented. ERL_DRV_EXTENDED_MINOR_VERSION will be incremented when new features are added. The runtime system uses the minor version of the driver to determine what features to use. The runtime system will normally refuse to load a driver if the major versions differ, or if the major versions are equal and the minor version used by the driver is greater than the one used by the runtime system. Old drivers with lower major versions will however be allowed after a bump of the major version during a transition period of two major releases. Such old drivers might however fail if deprecated features are used.

The emulator will refuse to load a driver that does not use the extended driver interface, to allow for 64-bit capable drivers, since incompatible type changes for the callbacks output, control and call were introduced in release R15B. A driver written with the old types would compile with warnings and when called return garbage sizes to the emulator causing it to read random memory and create huge incorrect result blobs.

Therefore it is not enough to just recompile drivers written with version management for pre-R15B types; the types have to be changed in the driver suggesting other rewrites especially regarding size variables. Investigate all warnings when recompiling!

Also, the API driver functions driver_output*, driver_vec_to_buf, driver_alloc/realloc* and the driver_* queue functions were changed to have larger length arguments and return values. This is a lesser problem since code that passes smaller types will get them auto converted in the calls and as long as the driver does not handle sizes that overflow an int all will work as before.

      REWRITES FOR 64-BIT DRIVER INTERFACE
    "

For erts-5.9 two new integer types ErlDrvSizeT and ErlDrvSSizeT were introduced that can hold 64-bit sizes if necessary.

To not update a driver and just recompile it probably works when building for a 32-bit machine creating a false sense of security. Hopefully that will generate many important warnings. But when recompiling the same driver later on for a 64-bit machine there will be warnings and almost certainly crashes. So it is a BAD idea to postpone updating the driver and not fixing the warnings!

When recompiling with gcc use the -Wstrict-prototypes flag to get better warnings. Try to find a similar flag if you are using some other compiler.

Here follows a checklist for rewriting a pre erts-5.9 driver, most important first.

Return types for driver callbacks: Rewrite driver callback control to use return type ErlDrvSSizeT instead of int.

Rewrite driver callback call to use return type ErlDrvSSizeT instead of int.

Note:

These changes are essential to not crash the emulator or worse cause malfunction. Without them a driver may return garbage in the high 32 bits to the emulator causing it to build a huge result from random bytes either crashing on memory allocation or succeeding with a random result from the driver call.

Arguments to driver callbacks: Driver callback output now gets ErlDrvSizeT as 3rd argument instead of previously int.

Driver callback control now gets ErlDrvSizeT as 4th and 6th arguments instead of previously int.

Driver callback call now gets ErlDrvSizeT as 4th and 6th arguments instead of previously int.

Sane compiler's calling conventions probably make these changes necessary only for a driver to handle data chunks that require 64-bit size fields (mostly larger than 2 GB since that is what an int of 32 bits can hold). But it is possible to think of non-sane calling conventions that would make the driver callbacks mix up the arguments causing malfunction.

Note:

The argument type change is from signed to unsigned which may cause problems for e.g. loop termination conditions or error conditions if you just change the types all over the place.

Larger size field in ErlIOVec: The size field in ErlIOVec has been changed to ErlDrvSizeT from int. Check all code that use that field.

Automatic type casting probably makes these changes necessary only for a driver that encounters sizes larger than 32 bits.

Note:

The size field changed from signed to unsigned which may cause problems for e.g. loop termination conditions or error conditions if you just change the types all over the place.

Arguments and return values in the driver API: Many driver API functions have changed argument type and/or return value to ErlDrvSizeT from mostly int. Automatic type casting probably makes these changes necessary only for a driver that encounters sizes larger than 32 bits.

: driver_output: 3rd argument
: driver_output2: 3rd and 5th arguments
: driver_output_binary: 3rd 5th and 6th arguments
: driver_outputv: 3rd and 5th arguments
: driver_vec_to_buf: 3rd argument and return value
: driver_alloc: 1st argument
: driver_realloc: 2nd argument
: driver_alloc_binary: 1st argument
: driver_realloc_binary: 2nd argument
: driver_enq: 3rd argument
: driver_pushq: 3rd argument
: driver_deq: 2nd argument and return value
: driver_sizeq: return value
: driver_enq_bin: 3rd and 4th argument
: driver_pushq_bin: 3rd and 4th argument
: driver_enqv: 3rd argument
: driver_pushqv: 3rd argument
: driver_peekqv: return value

Note:

This is a change from signed to unsigned which may cause problems for e.g. loop termination conditions and error conditions if you just change the types all over the place.

DATA TYPES

: ErlDrvSizeT: An unsigned integer type to be used as size_t
: ErlDrvSSizeT: A signed integer type the size of ErlDrvSizeT
: ErlDrvSysInfo:

typedef struct ErlDrvSysInfo {
   int driver_major_version;
   int driver_minor_version;
   char *erts_version;
   char *otp_release;
   int thread_support;
   int smp_support;
   int async_threads;
   int scheduler_threads;
   int nif_major_version;
   int nif_minor_version;
   int dirty_scheduler_support;
} ErlDrvSysInfo;

The ErlDrvSysInfo structure is used for storage of information about the Erlang runtime system. driver_system_info() will write the system information when passed a reference to a ErlDrvSysInfo structure. A description of the fields in the structure follows:

: driver_major_version: The value of ERL_DRV_EXTENDED_MAJOR_VERSION when the runtime system was compiled. This value is the same as the value of ERL_DRV_EXTENDED_MAJOR_VERSION used when compiling the driver; otherwise, the runtime system would have refused to load the driver.
: driver_minor_version: The value of ERL_DRV_EXTENDED_MINOR_VERSION when the runtime system was compiled. This value might differ from the value of ERL_DRV_EXTENDED_MINOR_VERSION used when compiling the driver.
: erts_version: A string containing the version number of the runtime system (the same as returned by erlang:system_info(version)).
: otp_release: A string containing the OTP release number (the same as returned by erlang:system_info(otp_release)).
: thread_support: A value != 0 if the runtime system has thread support; otherwise, 0.
: smp_support: A value != 0 if the runtime system has SMP support; otherwise, 0.
: async_threads: The number of async threads in the async thread pool used by driver_async() (the same as returned by erlang:system_info(thread_pool_size)).
: scheduler_threads: The number of scheduler threads used by the runtime system (the same as returned by erlang:system_info(schedulers)).
: nif_major_version: The value of ERL_NIF_MAJOR_VERSION when the runtime system was compiled.
: nif_minor_version: The value of ERL_NIF_MINOR_VERSION when the runtime system was compiled.
: dirty_scheduler_support: A value != 0 if the runtime system has support for dirty scheduler threads; otherwise 0.

: ErlDrvBinary:

typedef struct ErlDrvBinary {
   ErlDrvSint orig_size;
   char orig_bytes[];
} ErlDrvBinary;

The ErlDrvBinary structure is a binary, as sent between the emulator and the driver. All binaries are reference counted; when driver_binary_free is called, the reference count is decremented, when it reaches zero, the binary is deallocated. The orig_size is the size of the binary, and orig_bytes is the buffer. The ErlDrvBinary does not have a fixed size, its size is orig_size + 2 * sizeof(int).

Note:

The refc field has been removed. The reference count of an ErlDrvBinary is now stored elsewhere. The reference count of an ErlDrvBinary can be accessed via driver_binary_get_refc(), driver_binary_inc_refc(), and driver_binary_dec_refc().

Some driver calls, such as driver_enq_binary, increment the driver reference count, and others, such as driver_deq decrement it.

Using a driver binary instead of a normal buffer, is often faster, since the emulator doesn't need to copy the data, only the pointer is used.

A driver binary allocated in the driver, with driver_alloc_binary, should be freed in the driver (unless otherwise stated), with driver_free_binary. (Note that this doesn't necessarily deallocate it, if the driver is still referred in the emulator, the ref-count will not go to zero.)

Driver binaries are used in the driver_output2 and driver_outputv calls, and in the queue. Also the driver call-back outputv uses driver binaries.

If the driver for some reason or another, wants to keep a driver binary around, in a static variable for instance, the reference count should be incremented, and the binary can later be freed in the stop call-back, with driver_free_binary.

Note that since a driver binary is shared by the driver and the emulator, a binary received from the emulator or sent to the emulator, must not be changed by the driver.

Since erts version 5.5 (OTP release R11B), orig_bytes is guaranteed to be properly aligned for storage of an array of doubles (usually 8-byte aligned).

: ErlDrvData: The ErlDrvData is a handle to driver-specific data, passed to the driver call-backs. It is a pointer, and is most often type cast to a specific pointer in the driver.
: SysIOVec: This is a system I/O vector, as used by writev on unix and WSASend on Win32. It is used in ErlIOVec.
: ErlIOVec:

typedef struct ErlIOVec {
  int vsize;
  ErlDrvSizeT size;
  SysIOVec* iov;
  ErlDrvBinary** binv;
} ErlIOVec;

The I/O vector used by the emulator and drivers, is a list of binaries, with a SysIOVec pointing to the buffers of the binaries. It is used in driver_outputv and the outputv driver call-back. Also, the driver queue is an ErlIOVec.

ErlDrvMonitor: When a driver creates a monitor for a process, a ErlDrvMonitor is filled in. This is an opaque data-type which can be assigned to but not compared without using the supplied compare function (i.e. it behaves like a struct).

The driver writer should provide the memory for storing the monitor when calling driver_monitor_process. The address of the data is not stored outside of the driver, so the ErlDrvMonitor can be used as any other datum, it can be copied, moved in memory, forgotten etc.

ErlDrvNowData: The ErlDrvNowData structure holds a timestamp consisting of three values measured from some arbitrary point in the past. The three structure members are:

: megasecs: The number of whole megaseconds elapsed since the arbitrary point in time
: secs: The number of whole seconds elapsed since the arbitrary point in time
: microsecs: The number of whole microseconds elapsed since the arbitrary point in time

ErlDrvPDL: If certain port specific data have to be accessed from other threads than those calling the driver call-backs, a port data lock can be used in order to synchronize the operations on the data. Currently, the only port specific data that the emulator associates with the port data lock is the driver queue.

Normally a driver instance does not have a port data lock. If the driver instance wants to use a port data lock, it has to create the port data lock by calling driver_pdl_create(). NOTE: Once the port data lock has been created, every access to data associated with the port data lock has to be done while having the port data lock locked. The port data lock is locked, and unlocked, respectively, by use of driver_pdl_lock(), and driver_pdl_unlock().

A port data lock is reference counted, and when the reference count reaches zero, it will be destroyed. The emulator will at least increment the reference count once when the lock is created and decrement it once when the port associated with the lock terminates. The emulator will also increment the reference count when an async job is enqueued and decrement it after an async job has been invoked. Besides this, it is the responsibility of the driver to ensure that the reference count does not reach zero before the last use of the lock by the driver has been made. The reference count can be read, incremented, and decremented, respectively, by use of driver_pdl_get_refc(), driver_pdl_inc_refc(), and driver_pdl_dec_refc().

ErlDrvTid: Thread identifier.

See also: erl_drv_thread_create(), erl_drv_thread_exit(), erl_drv_thread_join(), erl_drv_thread_self(), and erl_drv_equal_tids().

ErlDrvThreadOpts:

	int suggested_stack_size;

Thread options structure passed to erl_drv_thread_create(). Currently the following fields exist:

: suggested_stack_size: A suggestion, in kilo-words, on how large a stack to use. A value less than zero means default size.

See also: erl_drv_thread_opts_create(), erl_drv_thread_opts_destroy(), and erl_drv_thread_create().

ErlDrvMutex: Mutual exclusion lock. Used for synchronizing access to shared data. Only one thread at a time can lock a mutex.

See also: erl_drv_mutex_create(), erl_drv_mutex_destroy(), erl_drv_mutex_lock(), erl_drv_mutex_trylock(), and erl_drv_mutex_unlock().

ErlDrvCond: Condition variable. Used when threads need to wait for a specific condition to appear before continuing execution. Condition variables need to be used with associated mutexes.

See also: erl_drv_cond_create(), erl_drv_cond_destroy(), erl_drv_cond_signal(), erl_drv_cond_broadcast(), and erl_drv_cond_wait().

ErlDrvRWLock: Read/write lock. Used to allow multiple threads to read shared data while only allowing one thread to write the same data. Multiple threads can read lock an rwlock at the same time, while only one thread can read/write lock an rwlock at a time.

See also: erl_drv_rwlock_create(), erl_drv_rwlock_destroy(), erl_drv_rwlock_rlock(), erl_drv_rwlock_tryrlock(), erl_drv_rwlock_runlock(), erl_drv_rwlock_rwlock(), erl_drv_rwlock_tryrwlock(), and erl_drv_rwlock_rwunlock().

ErlDrvTSDKey: Key which thread specific data can be associated with.

See also: erl_drv_tsd_key_create(), erl_drv_tsd_key_destroy(), erl_drv_tsd_set(), and erl_drv_tsd_get().

EXPORTS

void driver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size)

This function will write information about the Erlang runtime system into the ErlDrvSysInfo structure referred to by the first argument. The second argument should be the size of the ErlDrvSysInfo structure, i.e., sizeof(ErlDrvSysInfo).

See the documentation of the ErlDrvSysInfo structure for information about specific fields.

int driver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len)

The driver_output function is used to send data from the driver up to the emulator. The data will be received as terms or binary data, depending on how the driver port was opened.

The data is queued in the port owner process' message queue. Note that this does not yield to the emulator. (Since the driver and the emulator run in the same thread.)

The parameter buf points to the data to send, and len is the number of bytes.

The return value for all output functions is 0. (Unless the driver is used for distribution, in which case it can fail and return -1. For normal use, the output function always returns 0.)

int driver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)

The driver_output2 function first sends hbuf (length in hlen) data as a list, regardless of port settings. Then buf is sent as a binary or list. E.g. if hlen is 3 then the port owner process will receive [H1, H2, H3 | T].

The point of sending data as a list header, is to facilitate matching on the data received.

The return value is 0 for normal use.

int driver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len)

This function sends data to port owner process from a driver binary, it has a header buffer (hbuf and hlen) just like driver_output2. The hbuf parameter can be NULL.

The parameter offset is an offset into the binary and len is the number of bytes to send.

Driver binaries are created with driver_alloc_binary.

The data in the header is sent as a list and the binary as an Erlang binary in the tail of the list.

E.g. if hlen is 2, then the port owner process will receive [H1, H2 | <<T>>].

The return value is 0 for normal use.

Note that, using the binary syntax in Erlang, the driver application can match the header directly from the binary, so the header can be put in the binary, and hlen can be set to 0.

int driver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip)

This function sends data from an IO vector, ev, to the port owner process. It has a header buffer (hbuf and hlen), just like driver_output2.

The skip parameter is a number of bytes to skip of the ev vector from the head.

You get vectors of ErlIOVec type from the driver queue (see below), and the outputv driver entry function. You can also make them yourself, if you want to send several ErlDrvBinary buffers at once. Often it is faster to use driver_output or driver_output_binary.

E.g. if hlen is 2 and ev points to an array of three binaries, the port owner process will receive [H1, H2, <<B1>>, <<B2>> | <<B3>>].

The return value is 0 for normal use.

The comment for driver_output_binary applies for driver_outputv too.

ErlDrvSizeT driver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len)

This function collects several segments of data, referenced by ev, by copying them in order to the buffer buf, of the size len.

If the data is to be sent from the driver to the port owner process, it is faster to use driver_outputv.

The return value is the space left in the buffer, i.e. if the ev contains less than len bytes it's the difference, and if ev contains len bytes or more, it's 0. This is faster if there is more than one header byte, since the binary syntax can construct integers directly from the binary.

int driver_set_timer(ErlDrvPort port, unsigned long time)

This function sets a timer on the driver, which will count down and call the driver when it is timed out. The time parameter is the time in milliseconds before the timer expires.

When the timer reaches 0 and expires, the driver entry function timeout is called.

Note that there is only one timer on each driver instance; setting a new timer will replace an older one.

Return value is 0 (-1 only when the timeout driver function is NULL).

int driver_cancel_timer(ErlDrvPort port)

This function cancels a timer set with driver_set_timer.

The return value is 0.

int driver_read_timer(ErlDrvPort port, unsigned long *time_left)

This function reads the current time of a timer, and places the result in time_left. This is the time in milliseconds, before the timeout will occur.

The return value is 0.

int driver_get_now(ErlDrvNowData *now)

This function reads a timestamp into the memory pointed to by the parameter now. See the description of ErlDrvNowData for specification of its fields.

The return value is 0 unless the now pointer is not valid, in which case it is < 0.

int driver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on)

This function is used by drivers to provide the emulator with events to check for. This enables the emulator to call the driver when something has happened asynchronously.

The event argument identifies an OS-specific event object. On Unix systems, the functions select/poll are used. The event object must be a socket or pipe (or other object that select/poll can use). On windows, the Win32 API function WaitForMultipleObjects is used. This places other restrictions on the event object. Refer to the Win32 SDK documentation. On Enea OSE, the receive function is used. See the for more details.

The on parameter should be 1 for setting events and 0 for clearing them.

The mode argument is a bitwise-or combination of ERL_DRV_READ, ERL_DRV_WRITE and ERL_DRV_USE. The first two specify whether to wait for read events and/or write events. A fired read event will call ready_input while a fired write event will call ready_output.

Note:

Some OS (Windows and Enea OSE) do not differentiate between read and write events. The call-back for a fired event then only depends on the value of mode.

ERL_DRV_USE specifies if we are using the event object or if we want to close it. On an emulator with SMP support, it is not safe to clear all events and then close the event object after driver_select has returned. Another thread may still be using the event object internally. To safely close an event object call driver_select with ERL_DRV_USE and on==0. That will clear all events and then call stop_select when it is safe to close the event object. ERL_DRV_USE should be set together with the first event for an event object. It is harmless to set ERL_DRV_USE even though it already has been done. Clearing all events but keeping ERL_DRV_USE set will indicate that we are using the event object and probably will set events for it again.

Note:

ERL_DRV_USE was added in OTP release R13. Old drivers will still work as before. But it is recommended to update them to use ERL_DRV_USE and stop_select to make sure that event objects are closed in a safe way.

The return value is 0 (failure, -1, only if the ready_input/ready_output is NULL).

void *driver_alloc(ErlDrvSizeT size)

This function allocates a memory block of the size specified in size, and returns it. This only fails on out of memory, in that case NULL is returned. (This is most often a wrapper for malloc).

Memory allocated must be explicitly freed with a corresponding call to driver_free (unless otherwise stated).

This function is thread-safe.

void *driver_realloc(void *ptr, ErlDrvSizeT size)

This function resizes a memory block, either in place, or by allocating a new block, copying the data and freeing the old block. A pointer is returned to the reallocated memory. On failure (out of memory), NULL is returned. (This is most often a wrapper for realloc.)

This function is thread-safe.

void driver_free(void *ptr)

This function frees the memory pointed to by ptr. The memory should have been allocated with driver_alloc. All allocated memory should be deallocated, just once. There is no garbage collection in drivers.

This function is thread-safe.

ErlDrvBinary *driver_alloc_binary(ErlDrvSizeT size)

This function allocates a driver binary with a memory block of at least size bytes, and returns a pointer to it, or NULL on failure (out of memory). When a driver binary has been sent to the emulator, it must not be altered. Every allocated binary should be freed by a corresponding call to driver_free_binary (unless otherwise stated).

Note that a driver binary has an internal reference counter, this means that calling driver_free_binary it may not actually dispose of it. If it's sent to the emulator, it may be referenced there.

The driver binary has a field, orig_bytes, which marks the start of the data in the binary.

This function is thread-safe.

ErlDrvBinary *driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size)

This function resizes a driver binary, while keeping the data. The resized driver binary is returned. On failure (out of memory), NULL is returned.

This function is only thread-safe when the emulator with SMP support is used.

void driver_free_binary(ErlDrvBinary *bin)

This function frees a driver binary bin, allocated previously with driver_alloc_binary. Since binaries in Erlang are reference counted, the binary may still be around.

This function is only thread-safe when the emulator with SMP support is used.

long driver_binary_get_refc(ErlDrvBinary *bin)

Returns current reference count on bin.

This function is only thread-safe when the emulator with SMP support is used.

long driver_binary_inc_refc(ErlDrvBinary *bin)

Increments the reference count on bin and returns the reference count reached after the increment.

This function is only thread-safe when the emulator with SMP support is used.

long driver_binary_dec_refc(ErlDrvBinary *bin)

Decrements the reference count on bin and returns the reference count reached after the decrement.

This function is only thread-safe when the emulator with SMP support is used.

Note:

You should normally decrement the reference count of a driver binary by calling driver_free_binary(). driver_binary_dec_refc() does not free the binary if the reference count reaches zero. Only use driver_binary_dec_refc() when you are sure not to reach a reference count of zero.

int driver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len)

This function enqueues data in the driver queue. The data in buf is copied (len bytes) and placed at the end of the driver queue. The driver queue is normally used in a FIFO way.

The driver queue is available to queue output from the emulator to the driver (data from the driver to the emulator is queued by the emulator in normal erlang message queues). This can be useful if the driver has to wait for slow devices etc, and wants to yield back to the emulator. The driver queue is implemented as an ErlIOVec.

When the queue contains data, the driver won't close, until the queue is empty.

The return value is 0.