erl_driver

API functions for an Erlang driver

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!

Old drivers (compiled with an erl_driver.h from an
earlier erts version than 5.5.3) have to be recompiled
(but does not have to use the extended 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.

A driver is a library with a set of function that the emulator
calls, in response to Erlang functions and message
sending. There may be multiple instances of a driver, each
instance is connected to an Erlang 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_LOCKINGdriver 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.

Note!

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.

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:

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 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.

The emulator tries to check that a driver that doesn't use the
extended driver interface isn't incompatible when loading it.
It can, however, not make sure that it isn't incompatible. Therefore,
when loading a driver that doesn't use the extended driver
interface, there is a risk that it will be loaded also when
the driver is incompatible. When the driver uses the extended driver
interface, the emulator can verify that it isn't of an incompatible
driver version. You are therefore advised to use the extended driver
interface.

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:

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).

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 casted 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.

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, or canceled. 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().

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.

Functions

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, int 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.)

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.

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.

int driver_vec_to_buf(ErlIOVec *ev, char *buf, int 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.

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.

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) 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(size_t 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, size_t 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(int 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, int 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, int 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.

This function can be called from an arbitrary thread if a
port data lock
associated with the port is locked by the calling
thread during the call.

int driver_pushq(ErlDrvPort port, char* buf, int len)

This function puts data at the head of the driver queue. The
data in buf is copied (len bytes) and placed
at the beginning of the queue.

The return value is 0.

This function can be called from an arbitrary thread if a
port data lock
associated with the port is locked by the calling
thread during the call.

int driver_deq(ErlDrvPort port, int size)

This function dequeues data by moving the head pointer
forward in the driver queue by size bytes. The data
in the queue will be deallocated.

The return value is the number of bytes remaining in the queue
or -1 on failure.

This function can be called from an arbitrary thread if a
port data lock
associated with the port is locked by the calling
thread during the call.

int driver_sizeq(ErlDrvPort port)

This function returns the number of bytes currently in the
driver queue.

This function can be called from an arbitrary thread if a
port data lock
associated with the port is locked by the calling
thread during the call.

This function enqueues a driver binary in the driver
queue. The data in bin at offset with length
len is placed at the end of the queue. This function
is most often faster than driver_enq, because the
data doesn't have to be copied.

This function can be called from an arbitrary thread if a
port data lock
associated with the port is locked by the calling
thread during the call.

Start monitoring a process from a driver. When a process is
monitored, a process exit will result in a call to the
provided process_exit call-back
in the ErlDrvEntry
structure. The ErlDrvMonitor structure is filled in, for later
removal or compare.

This function is used to compare two ErlDrvMonitors. It
can also be used to imply some artificial order on monitors,
for whatever reason.

The function returns 0 if monitor1 and
monitor2 are equal, < 0 if monitor1 is less
than monitor2 and > 0 if monitor1 is greater
than monitor2.

void add_driver_entry(ErlDrvEntry *de)

This function adds a driver entry to the list of drivers
known by Erlang. The init function of the de
parameter is called.

Note!

To use this function for adding drivers residing in
dynamically loaded code is dangerous. If the driver code
for the added driver resides in the same dynamically
loaded module (i.e. .so file) as a normal
dynamically loaded driver (loaded with the erl_ddll
interface), the caller should call driver_lock_driver before
adding driver entries.

Use of this function is generally deprecated.

int remove_driver_entry(ErlDrvEntry *de)

This function removes a driver entry de previously
added with add_driver_entry.

Driver entries added by the erl_ddll erlang interface can
not be removed by using this interface.

char* erl_errno_id(int error)

This function returns the atom name of the erlang error,
given the error number in error. Error atoms are:
einval, enoent, etc. It can be used to make
error terms from the driver.

void set_busy_port(ErlDrvPort port, int on)

This function set and resets the busy status of the port. If
on is 1, the port is set to busy, if it's 0 the port
is set to not busy.

When the port is busy, sending to it with Port ! Data
or port_command/2, will block the port owner process,
until the port is signaled as not busy.

This function sets flags for how the control driver entry
function will return data to the port owner process. (The
control function is called from port_control/3
in erlang.)

Currently there are only two meaningful values for
flags: 0 means that data is returned in a list, and
PORT_CONTROL_FLAG_BINARY means data is returned as
a binary from control.

int driver_failure_eof(ErlDrvPort port)

This function signals to erlang that the driver has
encountered an EOF and should be closed, unless the port was
opened with the eof option, in that case eof is sent
to the port. Otherwise, the port is closed and an
'EXIT' message is sent to the port owner process.

The return value is 0.

int driver_failure_atom(ErlDrvPort port, char *string)

int driver_failure_posix(ErlDrvPort port, int error)

int driver_failure(ErlDrvPort port, int error)

These functions signal to Erlang that the driver has
encountered an error and should be closed. The port is
closed and the tuple {'EXIT', error, Err}, is sent to
the port owner process, where error is an error atom
(driver_failure_atom and
driver_failure_posix), or an integer
(driver_failure).

The driver should fail only when in severe error situations,
when the driver cannot possibly keep open, for instance
buffer allocation gets out of memory. For normal errors
it is more appropriate to send error codes with
driver_output.

The return value is 0.

ErlDrvTermData driver_connected(ErlDrvPort port)

This function returns the port owner process.

ErlDrvTermData driver_caller(ErlDrvPort port)

This function returns the process id of the process that
made the current call to the driver. The process id can be
used with driver_send_term to send back data to the
caller. driver_caller() only returns valid data
when currently executing in one of the following driver
callbacks:

This functions sends data in the special driver term
format. This is a fast way to deliver term data from a
driver. It also needs no binary conversion, so the port
owner process receives data as normal Erlang terms.

The term parameter points to an array of
ErlDrvTermData, with n elements. This array
contains terms described in the driver term format. Every
term consists of one to four elements in the array. The
term first has a term type, and then arguments.

Tuple and lists (with the exception of strings, see below),
are built in reverse polish notation, so that to build a
tuple, the elements are given first, and then the tuple
term, with a count. Likewise for lists.

A tuple must be specified with the number of elements. (The
elements precede the ERL_DRV_TUPLE term.)

A list must be specified with the number of elements,
including the tail, which is the last term preceding
ERL_DRV_LIST.

The special term ERL_DRV_STRING_CONS is used to
"splice" in a string in a list, a string given this way is
not a list per se, but the elements are elements of the
surrounding list.

The unsigned integer data type ErlDrvUInt and the
signed integer data type ErlDrvSInt are 64 bits wide
on a 64 bit runtime system and 32 bits wide on a 32 bit
runtime system. They were introduced in erts version 5.6,
and replaced some of the int arguments in the list above.

The unsigned integer data type ErlDrvUInt64 and the
signed integer data type ErlDrvSInt64 are always 64 bits
wide. They were introduced in erts version 5.7.4.

To build the tuple {tcp, Port, [100 | Binary]}, the
following call could be made.

Where bin is a driver binary of length at least 50
and port is a port handle. Note that the ERL_DRV_LIST
comes after the elements of the list, likewise the
ERL_DRV_TUPLE.

The term ERL_DRV_STRING_CONS is a way to construct
strings. It works differently from how ERL_DRV_STRING
works. ERL_DRV_STRING_CONS builds a string list in
reverse order, (as opposed to how ERL_DRV_LIST
works), concatenating the strings added to a list. The tail
must be given before ERL_DRV_STRING_CONS.

The ERL_DRV_STRING constructs a string, and ends
it. (So it's the same as ERL_DRV_NIL followed by
ERL_DRV_STRING_CONS.)

The ERL_DRV_EXT2TERM term type is used for passing a
term encoded with the
external format,
i.e., a term that has been encoded by
erlang:term_to_binary,
erl_interface, etc.
For example, if binp is a pointer to an ErlDrvBinary
that contains the term {17, 4711} encoded with the
external format
and you want to wrap it in a two tuple with the tag my_tag,
i.e., {my_tag, {17, 4711}}, you can do as follows:

If you want to pass a binary and don't already have the content
of the binary in an ErlDrvBinary, you can benefit from using
ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary
via driver_alloc_binary() and then pass the binary via
ERL_DRV_BINARY. The runtime system will often allocate
binaries smarter if ERL_DRV_BUF2BINARY is used.
However, if the content of the binary to pass already resides in
an ErlDrvBinary, it is normally better to pass the binary
using ERL_DRV_BINARY and the ErlDrvBinary in question.

The ERL_DRV_UINT, ERL_DRV_BUF2BINARY, and
ERL_DRV_EXT2TERM term types were introduced in the 5.6
version of erts.

Note that this function is not thread-safe, not
even when the emulator with SMP support is used.

ErlDrvTermData driver_mk_atom(char* string)

This function returns an atom given a name
string. The atom is created and won't change, so the
return value may be saved and reused, which is faster than
looking up the atom several times.

ErlDrvTermData driver_mk_port(ErlDrvPort port)

This function converts a port handle to the erlang term
format, usable in the driver_output_send function.

This function performs an asynchronous call. The function
async_invoke is invoked in a thread separate from the
emulator thread. This enables the driver to perform
time-consuming, blocking operations without blocking the
emulator.

Erlang is by default started without an async thread pool. The
number of async threads that the runtime system should use
is specified by the
+A
command line argument of erl(1).
If no async thread pool is available, the call is made
synchronously in the thread calling driver_async(). The
current number of async threads in the async thread pool can be
retrieved via
driver_system_info().

If there is a thread pool available, a thread will be
used. If the key argument is null, the threads from the
pool are used in a round-robin way, each call to
driver_async uses the next thread in the pool. With the
key argument set, this behaviour is changed. The two
same values of *key always get the same thread.

To make sure that a driver instance always uses the same
thread, the following call can be used:

If a thread is already working, the calls will be
queued up and executed in order. Using the same thread for
each driver instance ensures that the calls will be made in
sequence.

The async_data is the argument to the functions
async_invoke and async_free. It's typically a
pointer to a structure that contains a pipe or event that
can be used to signal that the async operation completed.
The data should be freed in async_free, because it's
called if driver_async_cancel is called.

When the async operation is done, ready_async driver
entry function is called. If async_ready is null in
the driver entry, the async_free function is called
instead.

The return value is a handle to the asynchronous task, which
can be used as argument to driver_async_cancel.

Note!

As of erts version 5.5.4.3 the default stack size for
threads in the async-thread pool is 16 kilowords,
i.e., 64 kilobyte on 32-bit architectures.
This small default size has been chosen since the
amount of async-threads might be quite large. The
default stack size is enough for drivers delivered
with Erlang/OTP, but might not be sufficiently large
for other dynamically linked in drivers that use the
driver_async() functionality. A suggested stack size
for threads in the async-thread pool can be configured
via the
+a
command line argument of
erl(1).

int driver_async_cancel(long id)

This function cancels an asynchronous operation, by removing
it from the queue. Only functions in the queue can be
cancelled; if a function is executing, it's too late to
cancel it. The async_free function is also called.

The return value is 1 if the operation was removed from the
queue, otherwise 0.

int driver_lock_driver(ErlDrvPort port)

This function locks the driver used by the port port
in memory for the rest of the emulator process'
lifetime. After this call, the driver behaves as one of Erlang's
statically linked in drivers.

The caller of driver_create_port() is allowed to
manipulate the newly created port when driver_create_port()
has returned. When
port level locking
is used, the creating port is, however, only allowed to
manipulate the newly created port until the current driver
call-back that was called by the emulator returns.

Note!

When
port level locking
is used, the creating port is only allowed to manipulate
the newly created port until the current driver call-back
returns.

A string identifying the created thread. It will be used
to identify the thread in planned future debug
functionality.

tid

A pointer to a thread identifier variable.

func

A pointer to a function to execute in the created thread.

arg

A pointer to argument to the func function.

opts

A pointer to thread options to use or NULL.

This function creates a new thread. On success 0 is returned;
otherwise, an errno value is returned to indicate the error.
The newly created thread will begin executing in the function pointed
to by func, and func will be passed arg as
argument. When erl_drv_thread_create() returns the thread
identifier of the newly created thread will be available in
*tid. opts can be either a NULL pointer, or a
pointer to an
ErlDrvThreadOpts
structure. If opts is a NULL pointer, default options
will be used; otherwise, the passed options will be used.

Warning!

The created thread will terminate either when func returns
or if
erl_drv_thread_exit()
is called by the thread. The exit value of the thread is either
returned from func or passed as argument to
erl_drv_thread_exit().
The driver creating the thread has the responsibility of joining the
thread, via
erl_drv_thread_join(),
before the driver is unloaded. It is not possible to create
"detached" threads, i.e., threads that don't need to be joined.

Warning!

All created threads need to be joined by the driver before
it is unloaded. If the driver fails to join all threads
created before it is unloaded, the runtime system will
most likely crash when the code of the driver is unloaded.

This function is thread-safe.

ErlDrvThreadOpts * erl_drv_thread_opts_create(char *name)

Arguments:

name

A string identifying the created thread options. It will be used
to identify the thread options in planned future debug
functionality.

This function allocates and initialize a thread option
structure. On failure NULL is returned. A thread option
structure is used for passing options to
erl_drv_thread_create().
If the structure isn't modified before it is passed to
erl_drv_thread_create(),
the default values will be used.

Warning!

You are not allowed to allocate the
ErlDrvThreadOpts
structure by yourself. It has to be allocated and
initialized by erl_drv_thread_opts_create().

This function terminates the calling thread with the exit
value passed as argument. You are only allowed to terminate
threads created with
erl_drv_thread_create().
The exit value can later be retrieved by another thread via
erl_drv_thread_join().

This function is thread-safe.

int erl_drv_thread_join(ErlDrvTid tid, void **exit_value)

Arguments:

tid

The thread identifier of the thread to join.

exit_value

A pointer to a pointer to an exit value, or NULL.

This function joins the calling thread with another thread, i.e.,
the calling thread is blocked until the thread identified by
tid has terminated. On success 0 is returned;
otherwise, an errno value is returned to indicate the error.
A thread can only be joined once. The behavior of joining
more than once is undefined, an emulator crash is likely. If
exit_value == NULL, the exit value of the terminated thread
will be ignored; otherwise, the exit value of the terminated thread
will be stored at *exit_value.

This function is thread-safe.

ErlDrvTid erl_drv_thread_self(void)

This function returns the thread identifier of the
calling thread.

This function is thread-safe.

int erl_drv_equal_tids(ErlDrvTid tid1, ErlDrvTid tid2)

Arguments:

tid1

A thread identifier.

tid2

A thread identifier.

This function compares two thread identifiers for equality,
and returns 0 it they aren't equal, and
a value not equal to 0 if they are equal.

Note!

A Thread identifier may be reused very quickly after
a thread has terminated. Therefore, if a thread
corresponding to one of the involved thread identifiers
has terminated since the thread identifier was saved,
the result of erl_drv_equal_tids() might not give
the expected result.

This function is thread-safe.

ErlDrvMutex * erl_drv_mutex_create(char *name)

Arguments:

name

A string identifying the created mutex. It will be used
to identify the mutex in planned future debug functionality.

This function creates a mutex and returns a pointer to it. On
failure NULL is returned. The driver creating the mutex
has the responsibility of destroying it before the driver is
unloaded.

This function is thread-safe.

void erl_drv_mutex_destroy(ErlDrvMutex *mtx)

Arguments:

mtx

A pointer to a mutex to destroy.

This function destroys a mutex previously created by
erl_drv_mutex_create().
The mutex has to be in an unlocked state before being
destroyed.

This function is thread-safe.

void erl_drv_mutex_lock(ErlDrvMutex *mtx)

Arguments:

mtx

A pointer to a mutex to lock.

This function locks a mutex. The calling thread will be
blocked until the mutex has been locked. A thread
which currently has locked the mutex may not lock
the same mutex again.

Warning!

If you leave a mutex locked in an emulator thread
when you let the thread out of your control, you will
very likely deadlock the whole emulator.

This function is thread-safe.

int erl_drv_mutex_trylock(ErlDrvMutex *mtx)

Arguments:

mtx

A pointer to a mutex to try to lock.

This function tries to lock a mutex. If successful 0,
is returned; otherwise, EBUSY is returned. A thread
which currently has locked the mutex may not try to
lock the same mutex again.

Warning!

If you leave a mutex locked in an emulator thread
when you let the thread out of your control, you will
very likely deadlock the whole emulator.

This function is thread-safe.

void erl_drv_mutex_unlock(ErlDrvMutex *mtx)

Arguments:

mtx

A pointer to a mutex to unlock.

This function unlocks a mutex. The mutex currently has to be
locked by the calling thread.

This function is thread-safe.

ErlDrvCond * erl_drv_cond_create(char *name)

Arguments:

name

A string identifying the created condition variable. It
will be used to identify the condition variable in planned
future debug functionality.

This function creates a condition variable and returns a
pointer to it. On failure NULL is returned. The driver
creating the condition variable has the responsibility of
destroying it before the driver is unloaded.

This function signals on a condition variable. That is, if
other threads are waiting on the condition variable being
signaled, one of them will be woken.

This function is thread-safe.

void erl_drv_cond_broadcast(ErlDrvCond *cnd)

Arguments:

cnd

A pointer to a condition variable to broadcast on.

This function broadcasts on a condition variable. That is, if
other threads are waiting on the condition variable being
broadcasted on, all of them will be woken.

This function is thread-safe.

void erl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx)

Arguments:

cnd

A pointer to a condition variable to wait on.

mtx

A pointer to a mutex to unlock while waiting.

This function waits on a condition variable. The calling
thread is blocked until another thread wakes it by signaling
or broadcasting on the condition variable. Before the calling
thread is blocked it unlocks the mutex passed as argument, and
when the calling thread is woken it locks the same mutex before
returning. That is, the mutex currently has to be locked by
the calling thread when calling this function.

Note!

erl_drv_cond_wait() might return even though
no-one has signaled or broadcasted on the condition
variable. Code calling erl_drv_cond_wait() should
always be prepared for erl_drv_cond_wait()
returning even though the condition that the thread was
waiting for hasn't occurred. That is, when returning from
erl_drv_cond_wait() always check if the condition
has occurred, and if not call erl_drv_cond_wait()
again.

This function is thread-safe.

ErlDrvRWLock * erl_drv_rwlock_create(char *name)

Arguments:

name

A string identifying the created rwlock. It will be used to
identify the rwlock in planned future debug functionality.

This function creates an rwlock and returns a pointer to it. On
failure NULL is returned. The driver creating the rwlock
has the responsibility of destroying it before the driver is
unloaded.

This function is thread-safe.

void erl_drv_rwlock_destroy(ErlDrvRWLock *rwlck)

Arguments:

rwlck

A pointer to an rwlock to destroy.

This function destroys an rwlock previously created by
erl_drv_rwlock_create().
The rwlock has to be in an unlocked state before being destroyed.

This function is thread-safe.

void erl_drv_rwlock_rlock(ErlDrvRWLock *rwlck)

Arguments:

rwlck

A pointer to an rwlock to read lock.

This function read locks an rwlock. The calling thread will be
blocked until the rwlock has been read locked. A thread
which currently has read or read/write locked the rwlock may
not lock the same rwlock again.

Warning!

If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
very likely deadlock the whole emulator.

This function is thread-safe.

int erl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck)

Arguments:

rwlck

A pointer to an rwlock to try to read lock.

This function tries to read lock an rwlock. If successful
0, is returned; otherwise, EBUSY is returned.
A thread which currently has read or read/write locked the
rwlock may not try to lock the same rwlock again.

Warning!

If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
very likely deadlock the whole emulator.

This function is thread-safe.

void erl_drv_rwlock_runlock(ErlDrvRWLock *rwlck)

Arguments:

rwlck

A pointer to an rwlock to read unlock.

This function read unlocks an rwlock. The rwlock currently
has to be read locked by the calling thread.

This function is thread-safe.

void erl_drv_rwlock_rwlock(ErlDrvRWLock *rwlck)

Arguments:

rwlck

A pointer to an rwlock to read/write lock.

This function read/write locks an rwlock. The calling thread
will be blocked until the rwlock has been read/write locked.
A thread which currently has read or read/write locked the
rwlock may not lock the same rwlock again.

Warning!

If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
very likely deadlock the whole emulator.

This function is thread-safe.

int erl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck)

Arguments:

rwlck

A pointer to an rwlock to try to read/write lock.

This function tries to read/write lock an rwlock. If successful
0, is returned; otherwise, EBUSY is returned.
A thread which currently has read or read/write locked the
rwlock may not try to lock the same rwlock again.

Warning!

If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
very likely deadlock the whole emulator.

This function is thread-safe.

void erl_drv_rwlock_rwunlock(ErlDrvRWLock *rwlck)

Arguments:

rwlck

A pointer to an rwlock to read/write unlock.

This function read/write unlocks an rwlock. The rwlock
currently has to be read/write locked by the calling thread.

This function is thread-safe.

int erl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key)

Arguments:

name

A string identifying the created key. It will be used
to identify the key in planned future debug
functionality.

key

A pointer to a thread specific data key variable.

This function creates a thread specific data key. On success
0 is returned; otherwise, an errno value is returned
to indicate the error. The driver creating the key has the
responsibility of destroying it before the driver is unloaded.

This function is thread-safe.

void erl_drv_tsd_key_destroy(ErlDrvTSDKey key)

Arguments:

key

A thread specific data key to destroy.

This function destroys a thread specific data key
previously created by
erl_drv_tsd_key_create().
All thread specific data using this key in all threads
have to be cleared (see
erl_drv_tsd_set())
prior to the call to erl_drv_tsd_key_destroy().

Warning!

A destroyed key is very likely to be reused soon.
Therefore, if you fail to clear the thread specific
data using this key in a thread prior to destroying
the key, you will very likely get unexpected
errors in other parts of the system.

This function is thread-safe.

void erl_drv_tsd_set(ErlDrvTSDKey key, void *data)

Arguments:

key

A thread specific data key.

data

A pointer to data to associate with key
in calling thread.

This function sets thread specific data associated with
key for the calling thread. You are only allowed to set
thread specific data for threads while they are fully under your
control. For example, if you set thread specific data in a thread
calling a driver call-back function, it has to be cleared, i.e.
set to NULL, before returning from the driver call-back
function.

Warning!

If you fail to clear thread specific data in an
emulator thread before letting it out of your control,
you might not ever be able to clear this data with
later unexpected errors in other parts of the system as
a result.

This function is thread-safe.

void * erl_drv_tsd_get(ErlDrvTSDKey key)

Arguments:

key

A thread specific data key.

This function returns the thread specific data
associated with key for the calling thread.
If no data has been associated with key for
the calling thread, NULL is returned.

This function is thread-safe.

int erl_drv_putenv(char *key, char *value)

Arguments:

key

A null terminated string containing the
name of the environment variable.

value

A null terminated string containing the
new value of the environment variable.

This function sets the value of an environment variable.
It returns 0 on success, and a value != 0 on
failure.

Note!

The result of passing the empty string ("") as a value
is platform dependent. On some platforms the value of the
variable is set to the empty string, on others, the
environment variable is removed.

Warning!

Do not use libc's putenv or similar
C library interfaces from a driver.

This function is thread-safe.

int erl_drv_getenv(char *key, char *value, size_t *value_size)

Arguments:

key

A null terminated string containing the
name of the environment variable.

value

A pointer to an output buffer.

value_size

A pointer to an integer. The integer is both used for
passing input and output sizes (see below).

This function retrieves the value of an environment variable.
When called, *value_size should contain the size of
the value buffer. On success 0 is returned,
the value of the environment variable has been written to
the value buffer, and *value_size contains the
string length (excluding the terminating null character) of
the value written to the value buffer. On failure,
i.e., no such environment variable was found, a value less than
0 is returned. When the size of the value
buffer is too small, a value greater than 0 is returned
and *value_size has been set to the buffer size needed.

Warning!

Do not use libc's getenv or similar
C library interfaces from a driver.