Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
erl_ddll - Dynamic Driver Loader and Linker
DESCRIPTION
The erl_ddll 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 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 and unload on a "when needed basis":
This (most common) scenario simply supports that each user of the driver loads it when
it is needed and unloads it when the user no longer have any use for it. The driver is
always reference counted and as long as a process keeping the driver loaded is still
alive, the driver is present in the system.
Each user of the driver use literally the same pathname for the driver when demanding
load, but the users are not really concerned with if the driver is already loaded from
the filesystem or if the object code has to be loaded from filesystem.
Two pairs of functions support this scenario:
load/2 and unload/1:
When using the 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.
If a process having the driver loaded dies, it will have the same effect as if
unloading was done.
When loading, the function 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.
load_driver/2 and unload_driver/1:
These interfaces is intended to be used when it is considered an error that ports
are open towards a driver that no user has loaded. The ports still open when the
last user calls unload_driver/1 or when the last process having the driver loaded
dies, will get killed with reason driver_unloaded.
The function names load_driver and unload_driver are kept for backward
compatibility.
Loading and reloading for code replacement:
This scenario occurs when the driver code might need replacement during operation of
the Erlang emulator. Implementing driver code replacement is somewhat more tedious
than beam code replacement, as one driver cannot be loaded as both "old" and "new"
code. All users of a driver must have it closed (no open ports) before the old code
can be unloaded and the new code can be loaded.
The actual unloading/loading is done as one atomic operation, blocking all processes
in the system from using the driver concerned 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 start, 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 than one user has the driver loaded.
The two functions for reloading drivers should be used together with corresponding
load functions, to support the two different behaviors concerning open ports:
load/2 and reload/2:
This pair of functions is used when reloading should be done after the last open
port towards the driver is closed.
As 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).
load_driver/2 and reload_driver/2:
This pair of functions are used when open ports towards the driver should be killed
with reason driver_unloaded to allow for new driver code to get loaded.
If, however, another process has the driver loaded, calling 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.
DATA TYPES
driver() = iolist() | atom()
path() = string() | atom()
EXPORTS
demonitor(MonitorRef) -> ok
Types:
MonitorRef = reference()
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 reference().
info() -> AllInfoList
Types:
AllInfoList = [DriverInfo]
DriverInfo = {DriverName, InfoList}
DriverName = string()
InfoList = [InfoItem]
InfoItem = {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.
info(Name) -> InfoList
Types:
Name = driver()
InfoList = [InfoItem, ...]
InfoItem = {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:
* processes
* driver_options
* port_count
* linked_in_driver
* permanent
* awaiting_load
* awaiting_unload
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.
info(Name, Tag) -> Value
Types:
Name = driver()
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:
processes:
Return all processes containing users of the specific drivers as a list of
tuples {pid(),integer() >= 0}, where the integer() denotes the number of users
in the process pid().
driver_options:
Return a list of the driver options provided when loading, as well as any
options set by the driver itself during initialization. The currently only
valid option being kill_ports.
port_count:
Return the number of ports (an integer >= 0()) using the driver.
linked_in_driver:
Return a boolean(), being true if the driver is a statically linked in one and
false otherwise.
permanent:
Return a boolean(), being true if the driver has made itself permanent (and is
not a statically linked in driver). false otherwise.
awaiting_load:
Return a list of all processes having monitors for loading active, each process
returned as {pid(),integer() >= 0}, where the integer() is the number of
monitors held by the process pid().
awaiting_unload:
Return a list of all processes having monitors for unloading active, each
process returned as {pid(),integer() >= 0}, where the integer() 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 = path()
Name = driver()
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:
Note especially that the Path is interpreted literally, so that all loaders of the
same driver needs to give the same literalPath string, even though different paths
might point out the same directory in the filesystem (due to 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 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 = path()
Name = driver()
ErrorDesc = term()
Works essentially as load/2, but will load the driver with 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 = driver()
When = loaded | unloaded | unloaded_only
MonitorRef = reference()
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:
Tag:
The monitor tag is always 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:
The 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 whose first element is the driver name and second element is
either of:
loaded:
Notify me when the driver is reloaded (or loaded if loading is underway). It
only makes sense to monitor drivers that are in the process of being loaded
or reloaded. One cannot monitor a future-to-be driver name for loading, that
will only result in a '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.
Setting a driver monitor for loading will eventually lead to one of the
following messages being sent:
{'UP', reference(), driver, Name, loaded}:
This message is sent, either immediately if the driver is already loaded
and no reloading is pending, or when reloading is executed if reloading is
pending.
The user is expected to know if reloading is demanded prior to creating a
monitor for loading.
{'UP', reference(), driver, Name, permanent}:
This message will be sent if reloading was expected, but the (old) driver
made itself permanent prior to reloading. It will also be sent if the
driver was permanent or statically linked in when trying to create the
monitor.
{'DOWN', reference(), driver, Name, load_cancelled}:
This message will arrive if reloading was underway, but the user having
requested reload cancelled it by either dying or calling try_unload/2 (or
unload/1/unload_driver/1) again before it was reloaded.
{'DOWN', reference(), driver, Name, {load_failure, Failure}}:
This message will arrive if reloading was underway but the loading for some
reason failed. The 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.
unloaded:
Monitor when a driver gets unloaded. If one monitors a driver that is not
present in the system, one will immediately get notified that the driver got
unloaded. There is no guarantee that the driver was actually ever loaded.
A driver monitor for unload will eventually result in one of the following
messages being sent:
{'DOWN', reference(), driver, Name, unloaded}:
The driver instance monitored is now unloaded. As the unload might have
been due to a reload/2 request, the driver might once again have been
loaded when this message arrives.
{'UP', reference(), driver, Name, unload_cancelled}:
This message will be sent if unloading was expected, but while the driver
was waiting for all ports to get closed, a new user of the driver appeared
and the unloading was cancelled.
This message appears when an {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.
If one wants to really monitor when the driver gets unloaded, this message
will distort the picture, no unloading was really done. The unloaded_only
option creates a monitor similar to an unloaded monitor, but does never
result in this message.
{'UP', reference(), driver, Name, permanent}:
This message will be sent if unloading was expected, but the driver made
itself permanent prior to unloading. It will also be sent if trying to
monitor a permanent or statically linked in driver.
unloaded_only:
A monitor created as unloaded_only behaves exactly as one created as unloaded
with the exception that the {'UP', reference(), 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 = path()
Name = driver()
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.
Note:
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.
Note:
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 = path()
Name = driver()
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 = path()
Name = driver()
OptionList = [Option]
Option = {driver_options, DriverOptionList}
| {monitor, MonitorOption}
| {reload, ReloadOption}
DriverOptionList = [DriverOption]
DriverOption = kill_ports
MonitorOption = ReloadOption = pending_driver | pending
Status = loaded | already_loaded | PendingStatus
PendingStatus = pending_driver | pending_process
Ref = reference()
ErrorDesc = ErrorAtom | OpaqueError
ErrorAtom = linked_in_driver
| inconsistent
| permanent
| not_loaded_by_this_process
| not_loaded
| pending_reload
| pending_process
OpaqueError = term()
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:
{ok, loaded}:
The driver was actually loaded and is immediately usable.
{ok, already_loaded}:
The driver was already loaded by another process and/or is in use by a living
port. The load by you is registered and a corresponding try_unload is expected
sometime in the future.
{ok, pending_driver}or {ok, pending_driver, reference()}:
The load request is registered, but the loading is delayed due to the fact that
an earlier instance of the driver is still waiting to get unloaded (there are
open ports using it). Still, unload is expected when you are done with the
driver. This return value will mostly happen when the {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_process}or {ok, pending_process, reference()}:
The load request is registered, but the loading is delayed due to the fact that
an earlier instance of the driver is still waiting to get unloaded by another
user (not only by a port, in which case {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, MonitorOption} 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, reference()} 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:
Note that in case of loading, monitoring can not only get triggered by using the
{reload, ReloadOption} option, but also in special cases where the load-error is
transient, why {monitor, pending_driver} should be used under basically all real
world circumstances!
The function accepts the following parameters:
Path:
The filesystem path to the directory where the driver object file is situated.
The filename of the object file (minus extension) must correspond to the driver
name (used in the name parameter) and the driver must identify itself with the
very same name. The Path might be provided as an iolist(), meaning it can be a
list of other iolist()s, characters (eight bit integers) or binaries, all to be
flattened into a sequence of characters.
The (possibly flattened) Path parameter must be consistent throughout the
system, a driver should, by all users, be loaded using the same literalPath.
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 newPath 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!
Name:
The name parameter is the name of the driver to be used in subsequent calls to
open_port. The name can be specified either as an iolist() 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 its filename.
OptionList:
A number of options can be specified to control the loading operation. The
options are given as a list of two-tuples, the tuples having the following
values and meanings:
{driver_options, DriverOptionList}:
This option is to provide options that will change its general behavior and
will "stick" to the driver throughout its lifespan.
The driver options for a given 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 actual name.
Currently the only allowed driver option is 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.
{monitor, MonitorOption}:
A 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, reference()}, where the reference() is the monitor
ref for the driver monitor.
Only one 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 ReloadOption if present.
If reloading is not requested, it might still be useful to specify the
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,ReloadOption}:
This option is used when one wants to reload a driver from disk, most often
in a code upgrade scenario. Having a reload option also implies that the Path
parameter need not be consistent with earlier loads of the driver.
To reload a driver, the process needs to have previously loaded the driver,
i.e there has to be an active user of the driver in the process.
The 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.
The more useful option is 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).
If the driver is unloaded (not present in the system), the error code
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:
{error,linked_in_driver}:
The driver with the specified name is an erlang statically linked in driver,
which cannot be manipulated with this API.
{error,inconsistent}:
The driver has already been loaded with either other DriverOptionList or a
different literalPath argument.
This can happen even if a reload option is given, if the DriverOptionList
differ from the current.
{error, permanent}:
The driver has requested itself to be permanent, making it behave like an
erlang linked in driver and it can no longer be manipulated with this API.
{error, pending_process}:
The driver is loaded by other users when the {reload, pending_driver} option
was given.
{error, pending_reload}:
Driver reload is already requested by another user when the {reload,
ReloadOption} option was given.
{error, not_loaded_by_this_process}:
Appears when the reload option is given. The driver Name is present in the
system, but there is no user of it in this process.
{error, not_loaded}:
Appears when the 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 = driver()
OptionList = [Option]
Option = {monitor, MonitorOption} | kill_ports
MonitorOption = pending_driver | pending
Status = unloaded | PendingStatus
PendingStatus = pending_driver | pending_process
Ref = reference()
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:
{ok, unloaded}:
The driver was immediately unloaded, meaning that the driver name is now free
to use by other drivers and, if the underlying OS permits it, the memory
occupied by the driver object code is now reclaimed.
The driver can only be unloaded when there are no open ports using it and there
are no more users requiring it to be loaded.
{ok, pending_driver}or {ok, pending_driver, reference()}:
This return value indicates that this call removed the last user from the
driver, but there are still open ports using it. When all ports are closed and
no new users have arrived, the driver will actually be reloaded and the name
and memory reclaimed.
This return value is valid even when the option 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.
{ok, pending_process}or {ok, pending_process, reference()}:
The unload request is registered, but there are still other users holding the
driver. Note that the term pending_process might refer to the running process,
there might be more than one user in the same process.
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 actually the
most common return value in the most common scenario described in the
introduction.
The function accepts the following parameters:
Name:
The name parameter is the name of the driver to be unloaded. The name can be
specified either as an iolist() or as an atom().
OptionList:
The OptionList argument can be used to specify certain behavior regarding ports
as well as triggering monitors under certain conditions:
kill_ports:
Force killing of all ports opened using this driver, with the exit reason
driver_unloaded, if you are the lastuser of the driver.
If there are other users having the driver loaded, this option will have no
effect.
If one wants the consistent behavior of killing ports when the last user
unloads, one should use the driver option kill_ports when loading the driver
instead.
{monitor, MonitorOption}:
This option creates a driver monitor if the condition given in MonitorOption
is true. The valid options are:
pending_driver:
Create a driver monitor if the return value is to be {ok, pending_driver}.
pending:
Create a monitor if the return value will be either {ok, pending_driver} or
{ok, pending_process}.
The 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.
By using the monitor-triggers in the call to 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):
{error, linked_in_driver}:
You were trying to unload an erlang statically linked in driver, which cannot
be manipulated with this interface (and cannot be unloaded at all).
{error, not_loaded}:
The driver Name is not present in the system.
{error, not_loaded_by_this_process}:
The driver Name is present in the system, but there is no user of it in this
process.
As a special case, drivers can be unloaded from processes that has done no
corresponding call to 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.
{error, permanent}:
The driver has made itself permanent, in which case it can no longer be
manipulated by this interface (much like a statically linked in driver).
The function throws a badarg exception if the parameters are not given as described
above.
unload(Name) -> ok | {error, ErrorDesc}
Types:
Name = driver()
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 = driver()
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 = term()
Takes an ErrorDesc returned by load, unload or reload functions and returns a
string which describes the error or warning.
Note:
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)!
SEE ALSO
erl_driver(5), driver_entry(5)