![[Erlang Systems]](min_head.gif)
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 takes 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 takes a parameter of type
ErlDrvBinary, a driver binary. It should be both
allocated and freed by the caller. Using a binary directly avoid
one extra copying of data.
Many of the output functions has 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.)
All functions that a driver needs to do with erlang are performed through driver API functions. There are functions for the following functionality:
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.
open_port/2. The vector function and the
function taking a driver binary is faster, because thet avoid
copying the data buffer. There is also a fast way of sending
terms from the driver, without going through the binary term
format.
int orig_sizeint refcchar orig_bytes[] 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 refc field 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,
increments the driver ref-count, and others, such as
driver_deq decrements 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,
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 of some reason or another, wants to keep a
driver binary around, in a static variable for instance, the
ref-count in the refc field 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, shouldn't be changed by the driver.
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.
This is a system I/O vector, as used by writev on
unix and WSASend on Win32. It is used in
ErlIOVec.
int vsizeint sizeSysIOVec* iovErlDrvBinary** binv 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.
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 runs 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, int hlen,
char *buf, int 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.
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, int hlen,
ErlIOVec *ev, int 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 ErlDriverBinary 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 i 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_select(ErlDrvPort port, ErlDrvEvent event, int
mode, int on)
The driver_select is used by the driver to
provide the emulator with an event to check for. This
enables the emulator to call the driver when something has
happened asynchronously.
The event parameter is used in the emulator cycle in
a select call. If the event is set then the driver is
called. The mode parameter can be either
ON_READ or ON_WRITE, and specifies whether
ready_output
or ready_input
will be called when the event is fired. Note that this is
just a convention, they don't have to read or write
anything.
The on parameter should be 1 for adding the
event and 0 for removing it.
On unix systems, the function select is used. The
event must be a socket or pipe (or other object that
select can use).
On windows, the Win32 API function
WaitForMultipleObjects is used. This places other
restriction on the event. Refer to the Win32 SDK
documentation.
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. Every
driver_alloc call must have a corresponding
driver_free.
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 ofthen a wrapper for realloc.)
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.
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 shouldn't be altered. Every
allocated binary should be freed.
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.
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.
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. Every call to driver_alloc_binary should have
a matching call to driver_free_binary.
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.
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.
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 dealloced.
The return value is 0.
int driver_sizeq(ErlDrvPort port)
This function returns the number of bytes currently in the driver queue.
int driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset,
int len)
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.
The return value is 0.
int driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset,
int len)
This function puts data in the binary bin, at
offset with length len at the head of the
driver queue. It is most often faster than
driver_pushq, because the data doesn't have to be
copied.
The return value is 0.
SysIOVec* driver_peekq(ErlDrvPort port, int *vlen)
This function retrieves the driver queue as a pointer to an
array of SysIOVecs. It also returns the number of
elements in vlen. This is the only way to get data
out of the queue.
Nothing is remove from the queue by this function, that must be done
with driver_deq.
The returned array is suitable to use with the unix system
call writev.
int driver_enqv(ErlDrvPort port, ErlIOVec *ev, int skip)
This function enqueues the data in ev, skipping the
first skip bytes of it, at the end of the driver
queue. It is faster than driver_enq, because the data
doesn't have to be copied.
The return value is 0.
int driver_pushqv(ErlDrvPort port, ErlIOVec *ev, int skip)
This function puts the data in ev, skipping the first
skip bytes of it, at the head of the driver queue.
It is faster than driver_pushq, because the data
doesn't have to be copied.
The return value is 0.
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.
int remove_driver_entry(ErlDrvEntry *de)
This function removes a driver entry de previously
added with add_driver_entry.
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.
void set_port_control_flags(ErlDrvPort port, int flags)
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 return from
control is sent to the port owner process.
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 close 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 kepp open, for instance
buffer allocation gets out of memory. Normal errors is more
appropriate to handle with sending error codes with
driver_output.
The return value is 0.
ErlDriverTerm driver_connected(ErlDrvPort port)
This function returns the port owner process.
ErlDriverTerm driver_caller(ErlDrvPort port)
This function returns the process that made the current call
to the driver. This can be used with driver_send_term
to send back data to the caller. (This is the process that
called one of erlang:send/2,
erlang:port_command/2 or
erlang:port_control/3).
int driver_output_term(ErlDrvPort port, ErlDriverTerm*
term, int n)
This functions sends data in the special driver term format. This is a fast way to deliver term data to 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
ErlDriverTerm, 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 precedes 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.
Term type Argument(s)
===========================================
ERL_DRV_NIL None
ERL_DRV_ATOM driver_mk_atom(string)
ERL_DRV_INT int
ERL_DRV_PORT driver_mk_port(ix)
ERL_DRV_BINARY ErlDriverBinary*, int len, int offset
ERL_DRV_STRING char*, int len
ERL_DRV_TUPLE int size
ERL_DRV_LIST int size
ERL_DRV_PID driver_connected,...
ERL_DRV_STRING_CONS char*, int len
To build the tuple {tcp, Port, [100 | Binary]}, the
following call could be made.
ErlDriverBinary* bin = ...
ErlDriverPort port = ...
ErlDriverTerm spec[] = {
ERL_DRV_ATOM, driver_mk_atom("tcp"),
ERL_DRV_PORT, driver_mk_port(port),
ERL_DRV_INT, 100,
ERL_DRV_BINARY, bin, 50, 0,
ERL_DRV_LIST, 2,
ERL_DRV_TUPLE, 3,
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
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.)
/* to send [x, "abc", y] to the port: */
ErlDriverTerm spec[] = {
ERL_DRV_ATOM, driver_mk_atom("x"),
ERL_DRV_STRING, (ErlDriverTerm)"abc", 3,
ERL_DRV_ATOM, driver_mk_atom("y"),
ERL_DRV_NIL,
ERL_DRV_LIST, 4
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
/* to send "abc123" to the port: */
ErlDriverTerm spec[] = {
ERL_DRV_NIL, /* with STRING_CONS, the tail comes first */
ERL_DRV_STRING_CONS, (ErlDriverTerm)"123", 3,
ERL_DRV_STRING_CONS, (ErlDriverTerm)"abc", 3,
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
ErlDriverTerm 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.
ErlDriverTerm driver_mk_port(ErlDrvPort port)
This function converts a port handle to the erlang term
format, usable in the driver_output_send function.
int driver_send_term(ErlDrvPort port, ErlDriverTerm
receiver, ErlDriverTerm* term, int n)
This function is the only way for a driver to send data to
other processes than the port owner process. The
receiver parameter specifies the process to receive
the data.
The parameters term and n does the same thing
as in driver_output_term.
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.
Normally, erlang is started without a thread pool. A start
argument to the emulator, specifies how many threads that
should be available (e.g. +A 5, gives five extra
driver threads). If no thread pool is available, the call is
made synchronously, in the emulator thread.
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:
r = driver_async(myPort, (unsigned char*)&myPort, myData, myFunc);
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.
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.
driver_entry(3), erl_ddll(3), erlang(3)
An Alternative Distribution Driver (ERTS User's Guide Ch. 3)