The erl_ddll
module provides an interface for loading
and unloading erlang linked in drivers in runtime.
This is a large reference document. For casual use of the module, as well as for most real world applications, the descriptions of the functions load/2 and unload/1 are enough to get going. |
The driver should be provided as a dynamically linked library
in a object code format specific for the platform in use,
i. e. .so
files on most Unix systems and .ddl
files on windows. An erlang linked in driver has to provide
specific interfaces to the emulator, so this module is not
designed for loading arbitrary dynamic libraries. For further
information about erlang drivers, refer to the ERTS reference
manual section erl_driver.
When describing a set of functions, (i.e. a module, a part of a module or an application) executing in a process and wanting to use a ddll-driver, we use the term user. There can be several users in one process (different modules needing the same driver) and several processes running the same code, making up several users of a driver. In the basic scenario, each user loads the driver before starting to use it and unloads the driver when done. The reference counting keeps track of processes as well as the number of loads by each process, so that the driver will only be unloaded when no one wants it (it has no user). The driver also keeps track of ports that are opened towards it, so that one can delay unloading until all ports are closed or kill all ports using the driver when it is unloaded.
The interface supports two basic scenarios of loading and unloading. Each scenario can also have the option of either killing ports when the driver is unloading, or waiting for the ports to close themselves. The scenarios are:
load/unload
interfaces, the
driver will not actually get unloaded until the
last port using the driver is closed. The function
unload/1
can return immediately, as the users are not really concerned
with when the actual unloading occurs. The
driver will actually get unloaded when no one needs it any longer.
load/2
returns
ok
as soon as there is any instance of the driver
present, so that if a driver is waiting to get unloaded
(due to open ports), it will simply change state to no
longer need unloading.
unload_driver/1
or when the last process having the
driver loaded dies, will get killed with reason
driver_unloaded
.
load_driver
and
unload_driver
are kept for backward
compatibility.
reload/2
actually waits for the reloading to
occur, a misbehaving process keeping open ports towards
the driver (or keeping the driver loaded) might cause
infinite waiting for reload. Timeouts has to be provided
outside of the process demanding the reload or by using
the low-level interface try_load/3 in combination
with driver monitors (see below).
driver_unloaded
to allow for new driver code to
get loaded.
reload_driver
returns the error code
pending_process
. As stated earlier,
the recommended design is to not allow other users than the "driver
reloader" to actually demand loading of the concerned
driver.
Types:
MonitorRef = ref()
Removes a driver monitor in much the same way as erlang:demonitor/1 does with process monitors. See monitor/2, try_load/3 and try_unload/2 for details about how to create driver monitors.
The function throws a badarg
exception if the
parameter is not a ref().
Types:
AllInfoList = [ DriverInfo ]
DriverInfo = {DriverName, InfoList}
DriverName = string()
InfoList = [ InfoItem ]
InfoItem = {Tag, Value}
Tag = atom()
Value = term()
Returns a list of tuples {DriverName, InfoList}
, where
InfoList
is the result of calling info/1 for that
DriverName
. Only dynamically linked in drivers are
included in the list.
Types:
Name = string() | atom()
InfoList = [ InfoItem ]
InfoItem = {Tag, Value}
Tag = atom()
Value = term()
Returns a list of tuples {Tag, Value}
, where
Tag
is the information item and Value
is the result
of calling info/2 with this driver name and
this tag. The result being a tuple list containing all
information available about a driver.
The different tags that will appear in the list are:
For a detailed description of each value, please read the description of info/2 below.
The function throws a badarg
exception if the driver
is not present in the system.
Types:
Name = string() | atom()
Tag = processes | driver_options | port_count |
linked_in_driver | permanent | awaiting_load | awaiting_unload
Value = term()
This function returns specific information about one aspect
of a driver. The Tag
parameter specifies which aspect
to get information about. The Value
return differs
between different tags:
{pid(),int()}
, where the
int()
denotes the number of users in the process
pid()
.
kill_ports
.
int()
) using the driver.
bool()
, being true
if the driver is a
statically linked in one and false
otherwise.
bool()
, being true
if the driver has made
itself permanent (and is not a statically
linked in driver). false
otherwise.
loading
active, each process returned as
{pid(),int()}
, where the int()
is the
number of monitors held by the process pid()
.
unloading
active, each process returned as
{pid(),int()}
, where the int()
is the
number of monitors held by the process pid()
.
If the options linked_in_driver
or permanent
return true, all other options will return the value
linked_in_driver
or permanent
respectively.
The function throws a badarg
exception if the driver
is not present in the system or the tag is not supported.
load(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = Name = string() | atom()
ErrorDesc = term()
Loads and links the dynamic driver Name
. Path
is a file path to the directory containing the driver.
Name
must be a sharable object/dynamic library. Two
drivers with different Path
parameters cannot be
loaded under the same name. The Name
is a string or
atom containing at least one character.
The Name
given should correspond to the filename
of the actual dynamically loadable object file residing in
the directory given as Path
, but without the
extension (i.e. .so
). The driver name provided in
the driver initialization routine must correspond with the
filename, in much the same way as erlang module names
correspond to the names of the .beam
files.
If the driver has been previously unloaded, but is still
present due to open ports against it, a call to
load/2
will stop the unloading and keep the driver
(as long as the Path
is the same) and ok
is
returned. If one actually wants the object code to be
reloaded, one uses reload/2 or the low-level
interface try_load/3
instead. Please refer to the description of different scenarios for
loading/unloading in the introduction.
If more than one process tries to load an already loaded
driver withe the same Path
, or if the same process
tries to load it several times, the function will return
ok
. The emulator will keep track of the
load/2
calls, so that a corresponding number of
unload/2
calls will have to be done from the same
process before the driver will actually get unloaded. It is
therefore safe for an application to load a driver that is
shared between processes or applications when needed. It can
safely be unloaded without causing trouble for other
parts of the system.
It is not allowed to load
several drivers with the same name but with different
Path
parameters.
Note especially that the |
On success, the function returns ok
. On
failure, the return value is {error,ErrorDesc}
,
where ErrorDesc
is an opaque term to be
translated into human readable form by the format_error/1
function.
For more control over the error handling, again use the try_load/3 interface instead.
The function throws a badarg
exception if the
parameters are not given as described above.
load_driver(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = Name = string() | atom()
ErrorDesc = term()
Works essentially as load/2
, but will load the driver
with options other options. All ports that are using the
driver will get killed with the reason
driver_unloaded
when the driver is to be unloaded.
The number of loads and unloads by different users influence the actual loading and unloading of a driver file. The port killing will therefore only happen when the last user unloads the driver, or the last process having loaded the driver exits.
This interface (or at least the name of the functions) is
kept for backward compatibility. Using try_load/3 with
{driver_options,[kill_ports]}
in the option list will
give the same effect regarding the port killing.
The function throws a badarg
exception if the
parameters are not given as described above.
monitor(Tag, Item) -> MonitorRef
Types:
Tag = driver
Item = {Name, When}
Name = atom() | string()
When = loaded | unloaded | unloaded_only
MonitorRef = ref()
This function creates a driver monitor and works in many
ways as the function erlang:monitor/2,
does for processes. When a driver changes state, the monitor
results in a monitor-message being sent to the calling
process. The MonitorRef
returned by this function is
included in the message sent.
As with process monitors, each driver monitor set will only generate one single message. The monitor is "destroyed" after the message is sent and there is then no need to call demonitor/1.
The MonitorRef
can also be used in subsequent calls
to demonitor/1 to
remove a monitor.
The function accepts the following parameters:
driver
as this function
can only be used to create driver monitors. In the future,
driver monitors will be integrated with process monitors,
why this parameter has to be given for consistence.
Item
parameter specifies which driver one
wants to monitor (the name of the driver) as well as
which state change one wants to monitor. The parameter
is a tuple of arity two who's first element is the
driver name and second element is either of:
'DOWN'
message being immediately sent.
Monitoring for loading is therefore most useful when
triggered by the try_load/3 function,
where the monitor is created because the
driver is in such a pending state.
loading
will
eventually lead to one of the following messages
being sent:
unload/1
/unload_driver/1
)
again before it was reloaded.
Failure
term is one of the
errors that can be returned from try_load/3. The
error term can be passed to format_error/1
for translation into human readable form. Note
that the translation has to be done in the same
running erlang virtual machine as the error
was detected in.
reload/2
request, the driver might once
again have been loaded when this message
arrives.
{ok,
pending_driver}
) was returned from try_unload/2)
for the last user of the driver and
then a {ok, already_loaded}
is returned
from a call to try_load/3.
unloaded_only
option creates a monitor
similar to an unloaded
monitor, but does
never result in this message.
unloaded_only
behaves
exactly as one created as unloaded
with the
exception that the {'UP', ref(), driver, Name,
unload_cancelled}
message will never be
sent, but the monitor instead persists until the
driver really gets unloaded.
The function throws a badarg
exception if the
parameters are not given as described above.
reload(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = Name = string() | atom()
ErrorDesc = pending_process | OpaqueError
OpaqueError = term()
Reloads the driver named Name
from a possibly
different Path
than was previously used. This
function is used in the code change scenario described in the
introduction.
If there are other users
of this driver, the function will return {error,
pending_process}
, but if there are no more users, the
function call will hang until all open ports are closed.
Avoid mixing several users with driver reload requests. |
If one wants to avoid hanging on open ports, one should use the try_load/3 function instead.
The Name
and Path
parameters have exactly the
same meaning as when calling the plain load/2 function.
Avoid mixing several users with driver reload requests. |
On success, the function returns ok
. On
failure, the function returns an opaque error, with the
exception of the pending_process
error described
above. The opaque errors are to be translated into human
readable form by the format_error/1 function.
For more control over the error handling, again use the try_load/3 interface instead.
The function throws a badarg
exception if the
parameters are not given as described above.
reload_driver(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = Name = string() | atom()
ErrorDesc = pending_process | OpaqueError
OpaqueError = term()
Works exactly as reload/2, but for drivers loaded with the load_driver/2 interface.
As this interface implies that ports are being killed when the last user disappears, the function wont hang waiting for ports to get closed.
For further details, see the scenarios in the module description and refer to the reload/2 function description.
The function throws a badarg
exception if the
parameters are not given as described above.
try_load(Path, Name, OptionList) -> {ok,Status} | {ok,
PendingStatus, Ref} | {error, ErrorDesc}
Types:
Path = Name = string() | atom()
OptionList = [ Option ]
Option = {driver_options, DriverOptionList} | {monitor,
MonitorOption} | {reload, ReloadOption}
DriverOptionList = [ DriverOption ]
DriverOption = kill_ports
MonitorOption = pending_driver | pending
ReloadOption = pending_driver | pending
Status = loaded | already_loaded | PendingStatus
PendingStatus = pending_driver | pending_process
Ref = ref()
ErrorDesc = ErrorAtom | OpaqueError
ErrorAtom = linked_in_driver | inconsistent |
permanent | not_loaded_by_this_process | not_loaded |
pending_reload | pending_process
This function provides more control than the
load/2
/reload/2
and
load_driver/2
/reload_driver/2
interfaces. It
will never wait for completion of other operations related
to the driver, but immediately return the status of the
driver as either:
try_unload
is
expected sometime in the future.
{reload,pending_driver}
or
{reload,pending}
options are used, but
can happen when another user is unloading a driver in
parallel and the kill_ports
driver option is
set. In other words, this return value will always need
to be handled!
{ok,pending_driver}
would
have been returned). Still, unload is expected when you
are done with the driver. This return value will
only happen when the {reload,pending}
option is used.
When the function returns {ok, pending_driver}
or
{ok, pending_process}
, one might want to get information
about when the driver is actually loaded. This can
be achieved by using the {monitor, PendingOption}
option.
When monitoring is requested, and a corresponding {ok,
pending_driver}
or {ok, pending_process}
would be
returned, the function will instead return a tuple {ok,
PendingStatus, ref()}
and the process will, at a later
time when the driver actually gets loaded, get a monitor
message. The monitor message one can expect is described in
the monitor/2
function description.
Note that in case of loading, monitoring can
not only get triggered by using the |
The function accepts the following parameters:
Path
might be provided as an io_list,
meaning it can be a list of other io_lists, characters
(eight bit integers) or binaries, all to be flattened
into a sequence of characters.
Path
parameter must be
consistent throughout the system, a driver should, by
all users, be loaded
using the same literal Path
. The
exception is when reloading is requested, in
which case the Path
may be specified
differently. Note that all users trying to load the
driver at a later time will need to use the new
Path
if the Path
is changed using a
reload
option. This is yet another reason
to have only one loader of a driver one wants to
upgrade in a running system! io_list()
or
as an atom()
. The name given when loading is used
to find the actual object file (with the
help of the Path
and the system implied
extension suffix, i.e. .so
). The name by which
the driver identifies itself must also be consistent
with this Name
parameter, much as a beam-file's
module name much correspond to it's filename.
kill_ports
, which means that all ports opened
towards the driver are killed with the exit-reason
driver_unloaded
when no process any longer
has the driver loaded. This situation arises either
when the last user calls try_unload/2, or
the last process having loaded the driver exits.
MonitorOption
tells try_load/3
to
trigger a driver monitor under certain
conditions. When the monitor is triggered, the
function will return a three-tuple {ok,
PendingStatus, ref()}
, where the ref()
is
the monitor ref for the driver monitor.
MonitorOption
can be specified and
it is either the atom pending
, which means
that a monitor should be created whenever a load
operation is delayed, and the atom
pending_driver
, in which a monitor is
created whenever the operation is delayed due to
open ports towards an otherwise unused driver. The
pending_driver
option is of little use, but
is present for completeness, it is very well defined
which reload-options might give rise to which
delays. It might, however, be a good idea to use the
same MonitorOption
as the RelaodOption
if present.
monitor
option, as
forced unloads (kill_ports
driver option or
the kill_ports
option to try_unload/2) will
trigger a transient state where driver loading
cannot be performed until all closing ports are
actually closed. So, as try_unload
can, in
almost all situations, return {ok,
pending_driver}
, one should always specify at least
{monitor, pending_driver}
in production
code (see the monitor discussion above).
reload
option
also implies that the Path
parameter need
not be consistent with earlier loads of
the driver.
reload
option can be either the atom
pending
, in which reloading is requested for
any driver and will be effectuated when all
ports opened against the driver are closed. The
replacement of the driver will in this case take
place regardless of if there are still
pending users
having the driver loaded!
The option also triggers port-killing (if the
kill_ports
driver option is used) even though
there are pending users, making it usable for forced
driver replacement, but laying a lot of
responsibility on the driver users. The pending option is
seldom used as one does not want other users to have loaded the
driver when code change is underway.
pending_driver
,
which means that reloading will be queued if the
driver is not loaded by any other users, but the driver has
opened ports, in which case {ok,
pending_driver}
will be returned (a
monitor
option is of course recommended).
not_loaded
will be returned. The
reload
option is intended for when the user
has already loaded the driver in advance.
The function might return numerous errors, of which some only can be returned given a certain combination of options.
A number of errors are opaque and can only be interpreted by passing them to the format_error/1 function, but some can be interpreted directly:
DriverOptions
or a different literal
Path
argument.
reload
option is given,
if the DriverOptions
differ from the current.
{reload,
pending_driver}
option was given.
{reload,
ReloadOption}
option was given.
reload
option is given. The
driver Name
is present in the system, but there is no
user of it in this
process.
reload
option is given. The
driver Name
is not in the system. Only drivers
loaded by this process can be reloaded.
All other error codes are to be translated by the format_error/1
function. Note that calls to format_error
should be
performed from the same running instance of the erlang
virtual machine as the error was detected in, due to system
dependent behavior concerning error values.
If the arguments or options are malformed, the function will
throw a badarg
exception.
try_unload(Name, OptionList) -> {ok,Status} | {ok,
PendingStatus, Ref} | {error, ErrorAtom}
Types:
Name = string() | atom()
OptionList = [ Option ]
Option = {monitor,
MonitorOption} | kill_ports
MonitorOption = pending_driver | pending
Status = unloaded | PendingStatus
PendingStatus = pending_driver | pending_process
Ref = ref()
ErrorAtom = linked_in_driver | not_loaded |
not_loaded_by_this_process | permanent
This is the low level function to unload (or decrement
reference counts of) a driver. It can be used to force port
killing, in much the same way as the driver option
kill_ports
implicitly does, and it can trigger a
monitor either due to other users still having the driver
loaded or that there are open ports using the driver.
Unloading can be described as the process of telling the
emulator that this particular part of the code in this
particular process (i.e. this user) no longer needs the
driver. That can, if there are no other users, trigger
actual unloading of the driver, in which case the driver
name disappears from the system and (if possible) the memory
occupied by the driver executable code is reclaimed. If the
driver has the kill_ports
option set, or if
kill_ports
was specified as an option to this
function, all pending ports using this driver will get
killed when unloading is done by the last user. If no port-killing is
involved and there are open ports, the actual unloading
is delayed until there are no more open ports using the
driver. If, in this case, another user (or even this user) loads the
driver again before the driver is actually unloaded, the
unloading will never take place.
To allow the user that
requests unloading to wait for actual unloading to
take place, monitor
triggers can be specified in much
the same way as when loading. As users of this function however
seldom are interested in more than decrementing the
reference counts, monitoring is more seldom needed. If the
kill_ports
option is used however, monitor trigging is
crucial, as the ports are not guaranteed to have been killed
until the driver is unloaded, why a monitor should be
triggered for at least the pending_driver
case.
The possible monitor messages that can be expected are the
same as when using the unloaded
option to the
monitor/2 function.
The function will return one of the following statuses upon success:
kill_ports
was used, as killing ports may not be
a process that completes immediately. The condition is,
in that case, however transient. Monitors are as always
useful to detect when the driver is really unloaded.
pending_process
might refer to the running process, there might be more
than one user in the
same process.
The function accepts the following parameters:
io_list()
or as an atom()
.
OptionList
argument can be used to specify
certain behavior regarding ports as well as triggering
monitors under certain conditions:
driver_unloaded
, if you are
the last user of the driver.
kill_ports
when loading the driver instead.
MonitorOptions
is true. The valid
options are:
{ok, pending_driver}
.
{ok, pending_driver}
or {ok,
pending_process}
.
pending_driver
MonitorOption
is by far
the most useful and it has to be used to ensure that the
driver has really been unloaded and the ports closed
whenever the kill_ports
option is used or the
driver may have been loaded with the kill_ports
driver option.
try_unload
one can be sure that the monitor is
actually added before the unloading is executed, meaning
that the monitor will always get properly triggered,
which would not be the case if one called
erl_ddll:monitor/2
separately.
The function may return several error conditions, of which all are well specified (no opaque values):
Name
is not present in the system.
Name
is present in the system, but
there is no user of
it in this process.
try_load/3
if, and only if, there are no
users of the driver at all, which may happen if the
process containing the last user dies.
The function throws a badarg
exception if the
parameters are not given as described above.
unload(Name) -> ok | {error, ErrorDesc}
Types:
Name = string() | atom()
ErrorDesc = term()
Unloads, or at least dereferences the driver named
Name
. If the caller is the last user of the driver, and there
are no more open ports using the driver, the driver will
actually get unloaded. In all other cases, actual unloading
will be delayed until all ports are closed and there are no
remaining users.
If there are other users of the driver, the reference counts of the driver is merely decreased, so that the caller is no longer considered a user of the driver. For usage scenarios, see the description in the beginning of this document.
The ErrorDesc
returned is an opaque value to be
passed further on to the format_error/1
function. For more control over the operation, use the
try_unload/2
interface.
The function throws a badarg
exception if the
parameters are not given as described above.
unload_driver(Name) -> ok | {error, ErrorDesc}
Types:
Name = string() | atom()
ErrorDesc = term()
Unloads, or at least dereferences the driver named
Name
. If the caller is the last user of the driver, all
remaining open ports using the driver will get killed with
the reason driver_unloaded
and the driver will
eventually get unloaded.
If there are other users of the driver, the reference counts of the driver is merely decreased, so that the caller is no longer considered a user. For usage scenarios, see the description in the beginning of this document.
The ErrorDesc
returned is an opaque value to be
passed further on to the format_error/1
function. For more control over the operation, use the
try_unload/2
interface.
The function throws a badarg
exception if the
parameters are not given as described above.
loaded_drivers() -> {ok, Drivers}
Types:
Drivers = [Driver()]
Driver = string()
Returns a list of all the available drivers, both (statically) linked-in and dynamically loaded ones.
The driver names are returned as a list of strings rather than a list of atoms for historical reasons.
More information about drivers can be obtained using one of the info functions.
format_error(ErrorDesc) -> string()
Types:
ErrorDesc -- see below
Takes an ErrorDesc
returned by load, unload or
reload functions and returns a string which
describes the error or warning.
Due to peculiarities in the dynamic loading interfaces on different platform, the returned string is only guaranteed to describe the correct error if format_error/1 is called in the same instance of the erlang virtual machine as the error appeared in (meaning the same operating system process)! |
erl_driver(4), driver_entry(4)