![]() |
![]()
| ![]() |
![]()
NAMEerl_ddll - Dynamic driver loader and linker.DESCRIPTIONThis module provides an interface for loading and unloading Erlang linked-in drivers in runtime.Note:
This is a large reference document. For casual use of this module, and for most
real world applications, the descriptions of functions load/2
and unload/1 are enough to getting started.
The driver is to be provided as a dynamically linked library in an object code
format specific for the platform in use, that is, .so files on most
Unix systems and .ddl files on Windows. An Erlang linked-in driver must
provide specific interfaces to the emulator, so this module is not designed
for loading arbitrary dynamic libraries. For more information about Erlang
drivers, see erts:erl_driver .
When describing a set of functions (that is, 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. A process can have many users (different modules needing
the same driver) and many processes running the same code, making up many
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
and the number of loads by each process. This way the driver is only unloaded
when no one wants it (it has no user). The driver also keeps track of ports
that are opened to it. This enables delay of unloading until all ports are
closed, or killing of all ports that use 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 as
follows:
Each user of the driver use literally the same pathname for the
driver when demanding load, but the users are not concerned with if the
driver is already loaded from the file system or if the object code must be
loaded from file system.
The following two pairs of functions support this scenario:
If a process having the driver loaded dies, it has the same effect as if
unloading is done.
When loading, function load/2 returns ok when any instance of the
driver is present. Thus, if a driver is waiting to get unloaded (because of
open ports), it simply changes state to no longer need unloading.
The function names load_driver and unload_driver are kept for
backward compatibility.
The unloading/loading is done as one atomic operation, blocking all processes in
the system from using the driver in question while in progress.
The preferred way to do driver code replacement is to let one single
process keep track of the driver. When the process starts, the driver is
loaded. When replacement is required, the driver is reloaded. Unload is
probably never done, or done when the process exits. If more than one
user has a driver loaded when code replacement is demanded, the
replacement cannot occur until the last "other" user has
unloaded the driver.
Demanding reload when a reload is already in progress is always an error. Using
the high-level functions, it is also an error to demand reloading when more
than one user has the driver loaded.
To simplify driver replacement, avoid designing your system so that more than
one user has the driver loaded.
The two functions for reloading drivers are to be used together with
corresponding load functions to support the two different behaviors concerning
open ports:
As reload/2 waits for the reloading to occur, a misbehaving process
keeping open ports to the driver (or keeping the driver loaded) can cause
infinite waiting for reload. Time-outs must be provided outside of the process
demanding the reload or by using the low-level interface
try_load/3 in combination with driver monitors.
However, if another process has the driver loaded, calling reload_driver
returns error code pending_process. As stated earlier, the recommended
design is to not allow other users than the "driver reloader"
to demand loading of the driver in question.
DATA TYPESdriver() = iolist() | atom() EXPORTSdemonitor(MonitorRef) -> ok
Types:
MonitorRef = reference()
Removes a driver monitor in much the same way as
erlang:demonitor/1 in ERTS does with process monitors. For
details about how to create driver monitors, see monitor/2,
try_load/3, and try_unload/2.
The function throws a badarg exception if the parameter is not a
reference().
format_error(ErrorDesc) -> string()
Types:
ErrorDesc = term()
Takes an ErrorDesc returned by load, unload, or reload functions and
returns a string that describes the error or warning.
Note:
Because of peculiarities in the dynamic loading interfaces on different
platforms, 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).
info() -> AllInfoList
Types:
AllInfoList = [DriverInfo]
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.
info(Name) -> InfoList
Types:
Name = driver()
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 is a tuple
list containing all information available about a driver.
The following tags appears in the list:
info(Name, Tag) -> Value
Types:
Name = driver()
processes | driver_options | port_count | linked_in_driver | permanent | awaiting_load | awaiting_unload
Returns specific information about one aspect of a driver. Parameter Tag
specifies which aspect to get information about. The return Value
differs between different tags:
load(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = path()
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. Name is a string or atom
containing at least one character.
The Name specified is to correspond to the filename of the dynamically
loadable object file residing in the directory specified as Path, but
without the extension (that is, .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 was previously unloaded, but is still present because of open
ports to it, a call to load/2 stops the unloading and keeps the driver
(as long as Path is the same), and ok is returned. If you really
want the object code to be reloaded, use reload/2 or the
low-level interface try_load/3 instead. See also the description
of different scenarios for loading/unloading in the
introduction.
If more than one process tries to load an already loaded driver with the same
Path, or if the same process tries to load it many times, the function
returns ok. The emulator keeps track of the load/2 calls, so
that a corresponding number of unload/2 calls must be done from the
same process before the driver gets 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 multiple drivers with the same name but with different
Path parameters.
Note:
Path is interpreted literally, so that all loaders of the same driver
must specify the same literal Path string, although different
paths can point out the same directory in the file system (because of use of
relative paths and links).
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 function format_error/1.
For more control over the error handling, use the try_load/3
interface instead.
The function throws a badarg exception if the parameters are not
specified as described here.load_driver(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = path()
Works essentially as load/2, but loads the driver with other options. All
ports using the driver are killed with reason driver_unloaded when the
driver is to be unloaded.
The number of loads and unloads by different users influences the loading
and unloading of a driver file. The port killing therefore only occurs when
the last user unloads the driver, or when 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 gives the same effect
regarding the port killing.
The function throws a badarg exception if the parameters are not
specified as described here.
loaded_drivers() -> {ok, Drivers}
Types:
Drivers = [Driver]
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.
For more information about drivers, see info.
monitor(Tag, Item) -> MonitorRef
Types:
Tag = driver
Creates a driver monitor and works in many ways as
erlang:monitor/2 in ERTS, does for processes. When a driver
changes state, the monitor results in a monitor message that is sent to the
calling process. MonitorRef returned by this function is included in
the message sent.
As with process monitors, each driver monitor set only generates one single
message. The monitor is "destroyed" after the message is sent,
so it is then not needed to call demonitor/1.
MonitorRef can also be used in subsequent calls to
demonitor/1 to remove a monitor.
The function accepts the following parameters:
Setting a driver monitor for loading eventually leads to one of the
following messages being sent:
The user is expected to know if reloading is demanded before creating a
monitor for loading.
A driver monitor for unload eventually results in one of the following messages
being sent:
This message appears if {ok, pending_driver} was returned from
try_unload/2 for the last user of the driver, and then
{ok, already_loaded} is returned from a call to
try_load/3.
If one really wants to monitor when the driver gets unloaded, this
message distorts the picture, because no unloading was done. Option
unloaded_only creates a monitor similar to an unloaded monitor,
but never results in this message.
reload(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = path()
Reloads the driver named Name from a possibly different Path than
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 returns {error,
pending_process}, but if there are no other users, the function call hangs
until all open ports are closed.
Note:
Avoid mixing multiple users with driver reload requests.
To avoid hanging on open ports, use function try_load/3 instead.
The Name and Path parameters have exactly the same meaning as when
calling the plain function load/2.
On success, the function returns ok. On failure, the function returns an
opaque error, except the pending_process error described earlier. The
opaque errors are to be translated into human readable form by function
format_error/1.
For more control over the error handling, use the try_load/3
interface instead.
The function throws a badarg exception if the parameters are not
specified as described here.reload_driver(Path, Name) -> ok | {error, ErrorDesc}
Types:
Path = path()
Works exactly as reload/2, but for drivers loaded with the
load_driver/2 interface.
As this interface implies that ports are killed when the last user disappears,
the function does not hang waiting for ports to get closed.
For more details, see scenarios in this module description and the
function description for reload/2.
The function throws a badarg exception if the parameters are not
specified as described here.
try_load(Path, Name, OptionList) -> {ok, Status} | {ok, PendingStatus, Ref} | {error, ErrorDesc}
Types:
Path = path()
{driver_options, DriverOptionList} | {monitor, MonitorOption} | {reload, ReloadOption} linked_in_driver | inconsistent | permanent | not_loaded_by_this_process | not_loaded | pending_reload | pending_process
Provides more control than the load/2/reload/2 and
load_driver/2/ reload_driver/2 interfaces. It never waits for
completion of other operations related to the driver, but immediately returns
the status of the driver as one of the following:
Note:
In case of loading, monitoring can not only get triggered by using option
{reload, ReloadOption}, but also in special cases where the load error
is transient. Thus, {monitor, pending_driver} is to be used under
basically all real world circumstances.
The function accepts the following parameters:
The (possibly flattened) Path parameter must be consistent throughout the
system. A driver is to, by all users, be loaded using the same
literal Path. The exception is when reloading is
requested, in which case Path can be specified differently. Notice that
all users trying to load the driver later need to use the new
Path if 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.
The driver options for a specified driver name need always to be consistent,
even when the driver is reloaded, meaning that they are as much a part
of the driver as the name.
The only allowed driver option is kill_ports, which means that all ports
opened to the driver are killed with 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 when the last
process having loaded the driver exits.
Only one MonitorOption can be specified. It is one of the
following:
Option pending_driver is of little use, but is present for completeness,
as it is well defined which reload options that can give rise to which delays.
However, it can be a good idea to use the same MonitorOption as the
ReloadOption, if present.
If reloading is not requested, it can still be useful to specify option
monitor, as forced unloads (driver option kill_ports or option
kill_ports to try_unload/2) trigger a transient state
where driver loading cannot be performed until all closing ports are closed.
Thus, as try_unload can, in almost all situations, return {ok,
pending_driver}, always specify at least {monitor, pending_driver}
in production code (see the monitor discussion earlier).
To reload a driver, the process must have loaded the driver before, that is,
there must be an active user of the driver in the process.
The reload option can be either of the following:
The option also triggers port-killing (if driver option kill_ports is
used) although there are pending users, making it usable for forced driver
replacement, but laying much 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.
If the driver is unloaded (not present in the system), error code
not_loaded is returned. Option reload is intended for when the
user has already loaded the driver in advance.
This can occur even if a reload option is specified, if
DriverOptionList differs from the current.
try_unload(Name, OptionList) -> {ok, Status} | {ok, PendingStatus, Ref} | {error, ErrorAtom}
Types:
Name = driver()
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. Also, it can trigger a
monitor either because other users still have the driver loaded or
because open ports use the driver.
Unloading can be described as the process of telling the emulator that this
particular part of the code in this particular process (that is, this
user) no longer needs the driver. That can, if there are no other
users, trigger 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 option kill_ports set, or if kill_ports is
specified as an option to this function, all pending ports using this driver
are killed when unloading is done by the last user. If no port-killing
is involved and there are open ports, the unloading is delayed until no more
open ports use the driver. If, in this case, another user (or even this
user) loads the driver again before the driver is unloaded, the unloading
never takes place.
To allow the user to request unloading to wait for actual
unloading, monitor triggers can be specified in much the same way
as when loading. However, as users of this function seldom are
interested in more than decrementing the reference counts, monitoring is
seldom needed.
Note:
If option kill_ports is used, monitor trigging is crucial, as the ports
are not guaranteed to be killed until the driver is unloaded. Thus, a monitor
must be triggered for at least the pending_driver case.
The possible monitor messages to expect are the same as when using option
unloaded to function monitor/2.
The function returns one of the following statuses upon success:
The driver can only be unloaded when there are no open ports using it and no
more users require it to be loaded.
This return value is valid even if option kill_ports was used, as killing
ports can be a process that does not complete immediately. However, the
condition is in that case transient. Monitors are always useful to detect when
the driver is really unloaded.
This is a normal, healthy, return value if the call was just placed to inform
the emulator that you have no further use of the driver. It is the most common
return value in the most common scenario described in the
introduction.
If other users have the driver loaded, this option has no effect.
To get the consistent behavior of killing ports when the last user
unloads, use driver option kill_ports when loading the driver
instead.
The pending_driver MonitorOption is by far the most useful. It
must be used to ensure that the driver really is unloaded and the ports closed
whenever option kill_ports is used, or the driver can have been loaded
with driver option kill_ports.
Using the monitor triggers in the call to try_unload ensures that the
monitor is added before the unloading is executed, meaning that the monitor is
always properly triggered, which is not the case if monitor/2 is called
separately.
As a special case, drivers can be unloaded from processes that have done no
corresponding call to try_load/3 if, and only if, there are no users
of the driver at all, which can occur if the process containing the last
user dies.
unload(Name) -> ok | {error, ErrorDesc}
Types:
Name = driver()
Unloads, or at least dereferences the driver named Name. If the caller is
the last user of the driver, and no more open ports use the driver, the
driver gets unloaded. Otherwise, unloading is delayed until all ports are
closed and no users remain.
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 use scenarios, see the
description in the beginning of this module.
The ErrorDesc returned is an opaque value to be passed further on to
function format_error/1. For more control over the operation,
use the try_unload/2 interface.
The function throws a badarg exception if the parameters are not
specified as described here.
unload_driver(Name) -> ok | {error, ErrorDesc}
Types:
Name = driver()
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
are killed with reason driver_unloaded and the driver eventually gets
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 use scenarios, see the description in the
beginning of this module.
The ErrorDesc returned is an opaque value to be passed further on to
function format_error/1. For more control over the operation,
use the try_unload/2 interface.
The function throws a badarg exception if the parameters are not
specified as described here.
SEE ALSOerts:erl_driver(4), erts:driver_entry(4)
|