diff options
Diffstat (limited to 'lib/kernel/doc/src/erl_ddll.xml')
| -rw-r--r-- | lib/kernel/doc/src/erl_ddll.xml | 1344 |
1 files changed, 718 insertions, 626 deletions
diff --git a/lib/kernel/doc/src/erl_ddll.xml b/lib/kernel/doc/src/erl_ddll.xml index 8d71883cf4..a5ce58ef3e 100644 --- a/lib/kernel/doc/src/erl_ddll.xml +++ b/lib/kernel/doc/src/erl_ddll.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2013</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,84 +29,91 @@ <rev></rev> </header> <module>erl_ddll</module> - <modulesummary>Dynamic Driver Loader and Linker</modulesummary> + <modulesummary>Dynamic driver loader and linker.</modulesummary> <description> - <p>The <c>erl_ddll</c> module provides an interface for loading - and unloading <em>erlang linked in drivers</em> in runtime.</p> + <p>This module provides an interface for loading + and unloading <em>Erlang linked-in drivers</em> in runtime.</p> <note> - <p>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 <seealso marker="#load/2">load/2</seealso> and <seealso marker="#unload/1">unload/1</seealso> are enough to get - going. </p> + <p>This is a large reference document. For casual use of this + module, and for most real world applications, the + descriptions of functions + <seealso marker="#load/2"><c>load/2</c></seealso> and + <seealso marker="#unload/1"><c>unload/1</c></seealso> + are enough to getting started.</p> </note> - <p>The driver should be provided as a dynamically linked library - in a object code format specific for the platform in use, - i. e. <c>.so</c> files on most Unix systems and <c>.ddl</c> - files on windows. An erlang linked in driver has to provide + <p>The driver is to be provided as a dynamically linked library + in an object code format specific for the platform in use, + that is, <c>.so</c> files on most Unix systems and <c>.ddl</c> + 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 further - information about erlang drivers, refer to the ERTS reference - manual section <seealso marker="erts:erl_driver">erl_driver</seealso>.</p> + designed for loading arbitrary dynamic libraries. For more + information about Erlang drivers, see + <seealso marker="erts:erl_driver"><c>erts:erl_driver</c></seealso> + .</p> <marker id="users"></marker> - <p>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 <em>user</em>. There can be - several users in one process (different modules needing the same - driver) and several processes running the same code, making up - several <em>users</em> 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. </p> + <p>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 <em>user</em>. A process can + have many users (different modules needing the same + driver) and many processes running the same code, making up + many <em>users</em> of a driver.</p> + <p>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.</p> <marker id="scenarios"></marker> <p>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:</p> + ports to close themselves. The scenarios are as follows:</p> <taglist> - <tag><em>Load and unload on a "when needed basis"</em></tag> + <tag><em>Load and Unload on a "When Needed Basis"</em></tag> <item> <p>This (most common) scenario simply supports that each <seealso marker="#users">user</seealso> of the driver loads - it when it is needed and unloads it when the <seealso marker="#users">user</seealso> no longer have any use for - it. The driver is always reference counted and as long as a + it when needed and unloads it when no longer needed. + 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.</p> <p>Each <seealso marker="#users">user</seealso> of the driver use <em>literally</em> the same pathname for the driver when - demanding load, but the <seealso marker="#users">users</seealso> 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.</p> - <p>Two pairs of functions support this scenario:</p> + demanding load, but the + <seealso marker="#users">users</seealso> 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.</p> + <p>The following two pairs of functions support this scenario:</p> <taglist> <tag><em>load/2 and unload/1</em></tag> <item> <p>When using the <c>load/unload</c> interfaces, the - driver will not <em>actually</em> get unloaded until the - <em>last port</em> using the driver is closed. The function - <c>unload/1</c> can return immediately, as the <seealso marker="#users">users</seealso> are not really concerned - with when the actual unloading occurs. The - driver will actually get unloaded when no one needs it any longer.</p> - <p>If a process having the driver loaded dies, it will have - the same effect as if unloading was done. </p> - <p>When loading, the function <c>load/2</c> returns - <c>ok</c> 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 + driver is not unloaded until the + <em>last port</em> using the driver is closed. Function + <c>unload/1</c> can return immediately, as the + <seealso marker="#users">users</seealso> + have no interrest in when the unloading occurs. The + driver is unloaded when no one needs it any longer.</p> + <p>If a process having the driver loaded dies, it has + the same effect as if unloading is done.</p> + <p>When loading, function <c>load/2</c> returns + <c>ok</c> 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.</p> </item> <tag><em>load_driver/2 and unload_driver/1</em></tag> <item> - <p>These interfaces is intended to be used when it is considered an - error that ports are open towards a driver that no <seealso marker="#users">user</seealso> - has loaded. The ports still open when the + <p>These interfaces are intended to be used when it is considered an + error that ports are open to a driver that no + <seealso marker="#users">user</seealso> + has loaded. The ports that are still open when the last <seealso marker="#users">user</seealso> calls <c>unload_driver/1</c> or when the last process having the - driver loaded dies, will get killed with reason + driver loaded dies, are killed with reason <c>driver_unloaded</c>.</p> <p>The function names <c>load_driver</c> and <c>unload_driver</c> are kept for backward @@ -114,60 +121,66 @@ </item> </taglist> </item> - <tag><em>Loading and reloading for code replacement</em></tag> + <tag><em>Loading and Reloading for Code Replacement</em></tag> <item> - <p>This scenario occurs when the driver code might need + <p>This scenario can occur if the driver code needs 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 <seealso marker="#users">users</seealso> of a driver must have it + emulator. Implementing driver code replacement is a little + more tedious than Beam code replacement, as one driver + cannot be loaded as both "old" and "new" code. All + <seealso marker="#users">users</seealso> of a driver must have it closed (no open ports) before the old code can be unloaded and the new code can be loaded.</p> - <p>The actual unloading/loading is done as one atomic + <p>The unloading/loading is done as one atomic operation, blocking all processes in the system from using - the driver concerned while in progress.</p> + the driver in question while in progress.</p> <p>The preferred way to do driver code replacement is to let <em>one single process</em> keep track of the driver. When - the process start, the driver is loaded. When replacement + 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 <seealso marker="#users">user</seealso> has a driver loaded when code - replacement is demanded, the replacement cannot occur until - the last "other" <seealso marker="#users">user</seealso> has + done, or done when the process exits. If more than one + <seealso marker="#users">user</seealso> has a driver + loaded when code replacement is demanded, the replacement cannot + occur until the last "other" + <seealso marker="#users">user</seealso> has unloaded the driver.</p> <p>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 <seealso marker="#users">user</seealso> has the driver loaded. To - simplify driver replacement, avoid designing your system so - that more than than one <seealso marker="#users">user</seealso> has the driver loaded.</p> - <p>The two functions for reloading drivers should be used - together with corresponding load functions, to support the two + always an error. Using the high-level functions, it is also + an error to demand reloading when more than one + <seealso marker="#users">user</seealso> has the driver loaded.</p> + <p>To simplify driver replacement, avoid designing your system so + that more than one + <seealso marker="#users">user</seealso> has the driver loaded.</p> + <p>The two functions for reloading drivers are to be used + together with corresponding load functions to support the two different behaviors concerning open ports:</p> <taglist> <tag><em>load/2 and reload/2</em></tag> <item> - <p>This pair of functions is used when reloading should be - done after the last open port towards the driver is + <p>This pair of functions is used when reloading is to be + done after the last open port to the driver is closed.</p> - <p>As <c>reload/2</c> 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 + <p>As <c>reload/2</c> 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 <seealso marker="#try_load/3">try_load/3</seealso> in combination - with driver monitors (see below).</p> + the low-level interface + <seealso marker="#try_load/3"><c>try_load/3</c></seealso> + in combination with driver monitors.</p> </item> <tag><em>load_driver/2 and reload_driver/2</em></tag> <item> - <p>This pair of functions are used when open ports towards - the driver should be killed with reason + <p>This pair of functions are used when open ports to + the driver are to be killed with reason <c>driver_unloaded</c> to allow for new driver code to get loaded.</p> - <p>If, however, another process has the driver loaded, - calling <c>reload_driver</c> returns the error code + <p>However, if another process has the driver loaded, + calling <c>reload_driver</c> returns error code <c>pending_process</c>. As stated earlier, - the recommended design is to not allow other <seealso marker="#users">users</seealso> than the "driver - reloader" to actually demand loading of the concerned - driver.</p> + the recommended design is to not allow other + <seealso marker="#users">users</seealso> than the "driver + reloader" to demand loading of the driver in question.</p> </item> </taglist> </item> @@ -184,903 +197,982 @@ <funcs> <func> <name name="demonitor" arity="1"/> - <fsummary>Remove a monitor for a driver</fsummary> + <fsummary>Remove a monitor for a driver.</fsummary> <desc> <p>Removes a driver monitor in much the same way as - <seealso marker="erts:erlang#erlang:demonitor/1">erlang:demonitor/1</seealso> does with process - monitors. See <seealso marker="#monitor/2">monitor/2</seealso>, <seealso marker="#try_load/3">try_load/3</seealso> and <seealso marker="#try_unload/2">try_unload/2</seealso> for details - about how to create driver monitors.</p> + <seealso marker="erts:erlang#erlang:demonitor/1"><c>erlang:demonitor/1</c></seealso> + in <c>ERTS</c> + does with process monitors. For details about how to create + driver monitors, see + <seealso marker="#monitor/2"><c>monitor/2</c></seealso>, + <seealso marker="#try_load/3"><c>try_load/3</c></seealso>, and + <seealso marker="#try_unload/2"><c>try_unload/2</c></seealso>.</p> <p>The function throws a <c>badarg</c> exception if the - parameter is not a reference(). </p> + parameter is not a <c>reference()</c>.</p> + </desc> + </func> + <func> + <name name="format_error" arity="1"/> + <fsummary>Format an error descriptor.</fsummary> + <desc> + <p>Takes an <c><anno>ErrorDesc</anno></c> returned by load, unload, or + reload functions and returns a string that + describes the error or warning.</p> + <note> + <p>Because of peculiarities in the dynamic loading interfaces on + different platforms, the returned string is only guaranteed + to describe the correct error <em>if format_error/1 is called + in the same instance of the Erlang virtual machine as the error + appeared in</em> (meaning the same operating + system process).</p> + </note> </desc> </func> <func> <name name="info" arity="0"/> - <fsummary>Retrieve information about all drivers</fsummary> + <fsummary>Retrieve information about all drivers.</fsummary> <desc> - <p>Returns a list of tuples <c>{<anno>DriverName</anno>, <anno>InfoList</anno>}</c>, where - <c><anno>InfoList</anno></c> is the result of calling <seealso marker="#info/1">info/1</seealso> for that - <c><anno>DriverName</anno></c>. Only dynamically linked in drivers are + <p>Returns a list of tuples <c>{<anno>DriverName</anno>, <anno>InfoList</anno>}</c>, + where <c><anno>InfoList</anno></c> is the result of calling + <seealso marker="#info/1"><c>info/1</c></seealso> for that + <c><anno>DriverName</anno></c>. Only dynamically linked-in drivers are included in the list.</p> </desc> </func> <func> <name name="info" arity="1"/> - <fsummary>Retrieve information about one driver</fsummary> + <fsummary>Retrieve information about one driver.</fsummary> <desc> - <p>Returns a list of tuples <c>{<anno>Tag</anno>, <anno>Value</anno>}</c>, where - <c><anno>Tag</anno></c> is the information item and <c><anno>Value</anno></c> is the result - of calling <seealso marker="#info/2">info/2</seealso> with this driver name and - this tag. The result being a tuple list containing all - information available about a driver. </p> - <p>The different tags that will appear in the list are:</p> + <p>Returns a list of tuples <c>{<anno>Tag</anno>, <anno>Value</anno>}</c>, + where <c><anno>Tag</anno></c> is the information item and + <c><anno>Value</anno></c> is the result of calling + <seealso marker="#info/2"><c>info/2</c></seealso> with this driver + name and this tag. The result is a tuple list containing all information + available about a driver.</p> + <p>The following tags appears in the list:</p> <list type="bulleted"> - <item>processes</item> - <item>driver_options</item> - <item>port_count</item> - <item>linked_in_driver</item> - <item>permanent</item> - <item>awaiting_load</item> - <item>awaiting_unload</item> + <item><c>processes</c></item> + <item><c>driver_options</c></item> + <item><c>port_count</c></item> + <item><c>linked_in_driver</c></item> + <item><c>permanent</c></item> + <item><c>awaiting_load</c></item> + <item><c>awaiting_unload</c></item> </list> - <p>For a detailed description of each value, please read the - description of <seealso marker="#info/2">info/2</seealso> below.</p> + <p>For a detailed description of each value, see + <seealso marker="#info/2"><c>info/2</c></seealso>.</p> <p>The function throws a <c>badarg</c> exception if the driver is not present in the system.</p> </desc> </func> <func> <name name="info" arity="2"/> - <fsummary>Retrieve specific information about one driver</fsummary> + <fsummary>Retrieve specific information about one driver.</fsummary> <desc> - <p>This function returns specific information about one aspect - of a driver. The <c><anno>Tag</anno></c> parameter specifies which aspect - to get information about. The <c><anno>Value</anno></c> return differs + <p>Returns specific information about one aspect of a driver. + Parameter <c><anno>Tag</anno></c> specifies which aspect + to get information about. The return <c><anno>Value</anno></c> differs between different tags:</p> <taglist> - <tag><em>processes</em></tag> + <tag><c>processes</c></tag> <item> - <p>Return all processes containing <seealso marker="#users">users</seealso> of the specific drivers - as a list of tuples <c>{pid(),integer() >= 0}</c>, where the - <c>integer()</c> denotes the number of users in the process + <p>Returns all processes containing + <seealso marker="#users">users</seealso> of the specific drivers + as a list of tuples <c>{pid(),integer() >= 0}</c>, where + <c>integer()</c> denotes the number of users in process <c>pid()</c>.</p> </item> - <tag><em>driver_options</em></tag> + <tag><c>driver_options</c></tag> <item> - <p>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 <c>kill_ports</c>.</p> + <p>Returns a list of the driver options provided when + loading, and any options set by the driver + during initialization. The only valid option + is <c>kill_ports</c>.</p> </item> - <tag><em>port_count</em></tag> + <tag><c>port_count</c></tag> <item> - <p>Return the number of ports (an <c>integer >= 0()</c>) using the driver.</p> + <p>Returns the number of ports (an <c>integer() >= 0</c>) + using the driver.</p> </item> - <tag><em>linked_in_driver</em></tag> + <tag><c>linked_in_driver</c></tag> <item> - <p>Return a <c>boolean()</c>, being <c>true</c> if the driver is a - statically linked in one and <c>false</c> otherwise.</p> + <p>Returns a <c>boolean()</c>, which is <c>true</c> if the driver is a + statically linked-in one, otherwise <c>false</c>.</p> </item> - <tag><em>permanent</em></tag> + <tag><c>permanent</c></tag> <item> - <p>Return a <c>boolean()</c>, being <c>true</c> if the driver has made - itself permanent (and is <em>not</em> a statically - linked in driver). <c>false</c> otherwise.</p> + <p>Returns a <c>boolean()</c>, which is <c>true</c> if the driver has + made itself permanent (and is <em>not</em> a statically + linked-in driver), otherwise <c>false</c>.</p> </item> - <tag><em>awaiting_load</em></tag> + <tag><c>awaiting_load</c></tag> <item> - <p>Return a list of all processes having monitors for - <c>loading</c> active, each process returned as - <c>{pid(),integer() >= 0}</c>, where the <c>integer()</c> is the - number of monitors held by the process <c>pid()</c>.</p> + <p>Returns a list of all processes having monitors for + <c>loading</c> active. Each process is returned as + <c>{pid(),integer() >= 0}</c>, where <c>integer()</c> is the + number of monitors held by process <c>pid()</c>.</p> </item> - <tag><em>awaiting_unload</em></tag> + <tag><c>awaiting_unload</c></tag> <item> - <p>Return a list of all processes having monitors for - <c>unloading</c> active, each process returned as - <c>{pid(),integer() >= 0}</c>, where the <c>integer()</c> is the - number of monitors held by the process <c>pid()</c>.</p> + <p>Returns a list of all processes having monitors for + <c>unloading</c> active. Each process is returned as + <c>{pid(),integer() >= 0}</c>, where <c>integer()</c> is the + number of monitors held by process <c>pid()</c>.</p> </item> </taglist> - <p>If the options <c>linked_in_driver</c> or <c>permanent</c> - return true, all other options will return the value - <c>linked_in_driver</c> or <c>permanent</c> respectively.</p> + <p>If option <c>linked_in_driver</c> or <c>permanent</c> + returns <c>true</c>, all other options return + <c>linked_in_driver</c> or <c>permanent</c>, respectively.</p> <p>The function throws a <c>badarg</c> exception if the driver - is not present in the system or the tag is not supported.</p> + is not present in the system or if the tag is not supported.</p> </desc> </func> <func> <name name="load" arity="2"/> - <fsummary>Load a driver</fsummary> + <fsummary>Load a driver.</fsummary> <desc> - <p>Loads and links the dynamic driver <c><anno>Name</anno></c>. <c><anno>Path</anno></c> + <p>Loads and links the dynamic driver <c><anno>Name</anno></c>. + <c><anno>Path</anno></c> is a file path to the directory containing the driver. <c><anno>Name</anno></c> must be a sharable object/dynamic library. Two drivers with different <c><anno>Path</anno></c> parameters cannot be - loaded under the same name. The <c><anno>Name</anno></c> is a string or + loaded under the same name. <c><anno>Name</anno></c> is a string or atom containing at least one character.</p> - <p>The <c><anno>Name</anno></c> given should correspond to the filename - of the actual dynamically loadable object file residing in - the directory given as <c><anno>Path</anno></c>, but <em>without</em> the - extension (i.e. <c>.so</c>). The driver name provided in + <p>The <c><anno>Name</anno></c> specified is to correspond to the filename + of the dynamically loadable object file residing in + the directory specified as <c><anno>Path</anno></c>, but <em>without</em> the + extension (that is, <c>.so</c>). The driver name provided in the driver initialization routine must correspond with the - filename, in much the same way as erlang module names + filename, in much the same way as Erlang module names correspond to the names of the <c>.beam</c> files.</p> - <p>If the driver has been previously unloaded, but is still - present due to open ports against it, a call to - <c>load/2</c> will stop the unloading and keep the driver - (as long as the <c><anno>Path</anno></c> is the same) and <c>ok</c> is - returned. If one actually wants the object code to be - reloaded, one uses <seealso marker="#reload/2">reload/2</seealso> or the low-level - interface <seealso marker="#try_load/3">try_load/3</seealso> - instead. Please refer to the description of <seealso marker="#scenarios">different scenarios</seealso> for + <p>If the driver was previously unloaded, but is still + present because of open ports to it, a call to + <c>load/2</c> stops the unloading and keeps the driver + (as long as <c><anno>Path</anno></c> is the same), and <c>ok</c> is + returned. If you really want the object code to be + reloaded, use <seealso marker="#reload/2"><c>reload/2</c></seealso> + or the low-level interface + <seealso marker="#try_load/3"><c>try_load/3</c></seealso> instead. + See also the description of + <seealso marker="#scenarios"><c>different scenarios</c></seealso> for loading/unloading in the introduction.</p> <p>If more than one process tries to load an already loaded - driver withe the same <c><anno>Path</anno></c>, or if the same process - tries to load it several times, the function will return - <c>ok</c>. The emulator will keep track of the + driver with the same <c><anno>Path</anno></c>, or if the same process + tries to load it many times, the function returns + <c>ok</c>. The emulator keeps track of the <c>load/2</c> calls, so that a corresponding number of - <c>unload/2</c> calls will have to be done from the same - process before the driver will actually get unloaded. It is + <c>unload/2</c> 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. </p> - <p>It is not allowed to load - several drivers with the same name but with different - <c>Path</c> parameters.</p> + parts of the system.</p> + <p>It is not allowed to load multiple drivers with + the same name but with different <c>Path</c> parameters.</p> <note> - <p>Note especially that the <c><anno>Path</anno></c> is interpreted - literally, so that all loaders of the same driver needs to - give the same <em>literal</em><c><anno>Path</anno></c> string, even - though different paths might point out the same directory - in the filesystem (due to use of relative paths and + <p><c><anno>Path</anno></c> is interpreted + literally, so that all loaders of the same driver must + specify the same <em>literal</em> <c><anno>Path</anno></c> string, + although different paths can point out the same directory + in the file system (because of use of relative paths and links).</p> </note> <p>On success, the function returns <c>ok</c>. On failure, the return value is <c>{error,<anno>ErrorDesc</anno>}</c>, where <c><anno>ErrorDesc</anno></c> is an opaque term to be - translated into human readable form by the <seealso marker="#format_error/1">format_error/1</seealso> - function.</p> - <p>For more control over the error handling, again use the - <seealso marker="#try_load/3">try_load/3</seealso> + translated into human readable form by function + <seealso marker="#format_error/1"><c>format_error/1</c></seealso>.</p> + <p>For more control over the error handling, use the + <seealso marker="#try_load/3"><c>try_load/3</c></seealso> interface instead.</p> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> + parameters are not specified as described here.</p> </desc> </func> <func> <name name="load_driver" arity="2"/> - <fsummary>Load a driver</fsummary> + <fsummary>Load a driver.</fsummary> <desc> - <p>Works essentially as <c>load/2</c>, but will load the driver - with other options. All ports that are using the - driver will get killed with the reason - <c>driver_unloaded</c> when the driver is to be unloaded.</p> - <p>The number of loads and unloads by different <seealso marker="#users">users</seealso> influence the actual loading - and unloading of a driver file. The port killing will - therefore only happen when the <em>last</em> <seealso marker="#users">user</seealso> unloads the driver, or the - last process having loaded the driver exits.</p> + <p>Works essentially as <c>load/2</c>, but loads the driver + with other options. All ports using the + driver are killed with reason <c>driver_unloaded</c> + when the driver is to be unloaded.</p> + <p>The number of loads and unloads by different + <seealso marker="#users">users</seealso> influences the loading + and unloading of a driver file. The port killing + therefore only occurs when the <em>last</em> + <seealso marker="#users">user</seealso> unloads the driver, + or when the last process having loaded the driver exits.</p> <p>This interface (or at least the name of the functions) is - kept for backward compatibility. Using <seealso marker="#try_load/3">try_load/3</seealso> with - <c>{driver_options,[kill_ports]} </c> in the option list will - give the same effect regarding the port killing.</p> + kept for backward compatibility. + Using <seealso marker="#try_load/3"><c>try_load/3</c></seealso> with + <c>{driver_options,[kill_ports]}</c> in the option list + gives the same effect regarding the port killing.</p> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> + parameters are not specified as described here.</p> + </desc> + </func> + <func> + <name name="loaded_drivers" arity="0"/> + <fsummary>List loaded drivers.</fsummary> + <desc> + <p>Returns a list of all the available drivers, both + (statically) linked-in and dynamically loaded ones.</p> + <p>The driver names are returned as a list of strings rather + than a list of atoms for historical reasons.</p> + <p>For more information about drivers, see + <seealso marker="#info/0"><c>info</c></seealso>.</p> </desc> </func> <func> <name name="monitor" arity="2"/> - <fsummary>Create a monitor for a driver</fsummary> + <fsummary>Create a monitor for a driver.</fsummary> <desc> - <p>This function creates a driver monitor and works in many - ways as the function <seealso marker="erts:erlang#erlang:monitor/2">erlang:monitor/2</seealso>, + <p>Creates a driver monitor and works in many + ways as + <seealso marker="erts:erlang#erlang:monitor/2"><c>erlang:monitor/2</c></seealso> + in <c>ERTS</c>, does for processes. When a driver changes state, the monitor - results in a monitor-message being sent to the calling - process. The <c><anno>MonitorRef</anno></c> returned by this function is + results in a monitor message that is sent to the calling + process. <c><anno>MonitorRef</anno></c> returned by this function is included in the message sent.</p> - <p>As with process monitors, each driver monitor set will only - generate <em>one single message</em>. The monitor is - "destroyed" after the message is sent and there is then no - need to call <seealso marker="#demonitor/1">demonitor/1</seealso>.</p> - <p>The <c><anno>MonitorRef</anno></c> can also be used in subsequent calls - to <seealso marker="#demonitor/1">demonitor/1</seealso> to + <p>As with process monitors, each driver monitor set only + generates <em>one single message</em>. The monitor is + "destroyed" after the message is sent, so it is then not + needed to call + <seealso marker="#demonitor/1"><c>demonitor/1</c></seealso>.</p> + <p><c><anno>MonitorRef</anno></c> can also be used in subsequent calls + to <seealso marker="#demonitor/1"><c>demonitor/1</c></seealso> to remove a monitor.</p> <p>The function accepts the following parameters:</p> <taglist> - <tag><em><c><anno>Tag</anno></c></em></tag> + <tag><c><anno>Tag</anno></c></tag> <item> - <p>The monitor tag is always <c>driver</c> as this function + <p>The monitor tag is always <c>driver</c>, 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.</p> + why this parameter has to be specified for consistence.</p> </item> - <tag><em><c><anno>Item</anno></c></em></tag> + <tag><c><anno>Item</anno></c></tag> <item> - <p>The <c><anno>Item</anno></c> 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 + <p>Parameter <c><anno>Item</anno></c> specifies + which driver to monitor (the driver name) and + which state change to monitor. The parameter is a tuple of arity two whose first element is the - driver name and second element is either of:</p> + driver name and second element is one of the following:</p> <taglist> - <tag><em>loaded</em></tag> + <tag><c>loaded</c></tag> <item> - <p>Notify me when the driver is reloaded (or loaded if + <p>Notifies 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 - <c>'DOWN'</c> message being immediately sent. + reloaded. A future driver name for loading cannot be + monitored. That only results in a + <c>DOWN</c> message sent immediately. Monitoring for loading is therefore most useful when - triggered by the <seealso marker="#try_load/3">try_load/3</seealso> function, + triggered by function + <seealso marker="#try_load/3"><c>try_load/3</c></seealso>, where the monitor is created <em>because</em> the driver is in such a pending state.</p> - <p>Setting a driver monitor for <c>loading</c> will - eventually lead to one of the following messages + <p>Setting a driver monitor for <c>loading</c> + eventually leads to one of the following messages being sent:</p> <taglist> - <tag><em>{'UP', reference(), driver, Name, loaded}</em></tag> + <tag><c>{'UP', reference(), driver, Name, loaded}</c></tag> <item> - <p>This message is sent, either immediately if the + <p>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. </p> <p>The <seealso marker="#users">user</seealso> is - expected to know if reloading is demanded prior - to creating a monitor for loading.</p> + expected to know if reloading is demanded before + creating a monitor for loading.</p> </item> - <tag><em>{'UP', reference(), driver, Name, permanent}</em></tag> + <tag><c>{'UP', reference(), driver, Name, permanent}</c></tag> <item> - <p>This message will be sent if reloading was + <p>This message is sent if reloading was expected, but the (old) driver made itself - permanent prior to reloading. It will also be + permanent before reloading. It is also sent if the driver was permanent or statically - linked in when trying to create the monitor.</p> + linked-in when trying to create the monitor.</p> </item> - <tag><em>{'DOWN', reference(), driver, Name, load_cancelled}</em></tag> + <tag><c>{'DOWN', reference(), driver, Name, load_cancelled}</c></tag> <item> - <p>This message will arrive if reloading was - underway, but the <seealso marker="#users">user</seealso> having requested - reload cancelled it by either dying or calling - <seealso marker="#try_unload/2">try_unload/2</seealso> + <p>This message arrives if reloading was + underway, but the requesting + <seealso marker="#users">user</seealso> + cancelled it by dying or calling + <seealso marker="#try_unload/2"><c>try_unload/2</c></seealso> (or <c>unload/1</c>/<c>unload_driver/1</c>) again before it was reloaded.</p> </item> - <tag><em>{'DOWN', reference(), driver, Name, {load_failure, Failure}}</em></tag> + <tag><c>{'DOWN', reference(), driver, Name, {load_failure, Failure}}</c></tag> <item> - <p>This message will arrive if reloading was + <p>This message arrives if reloading was underway but the loading for some reason failed. The <c>Failure</c> term is one of the - errors that can be returned from <seealso marker="#try_load/3">try_load/3</seealso>. The - error term can be passed to <seealso marker="#format_error/1">format_error/1</seealso> - for translation into human readable form. Note - that the translation has to be done in the same - running erlang virtual machine as the error + errors that can be returned from + <seealso marker="#try_load/3"><c>try_load/3</c></seealso>. + The error term can be passed to + <seealso marker="#format_error/1"><c>format_error/1</c></seealso> + for translation into human readable form. Notice + that the translation must be done in the same + running Erlang virtual machine as the error was detected in.</p> </item> </taglist> </item> - <tag><em>unloaded</em></tag> + <tag><c>unloaded</c></tag> <item> - <p>Monitor when a driver gets unloaded. If one + <p>Monitors 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 + one immediately gets notified that the driver got unloaded. There is no guarantee that the driver was - actually ever loaded.</p> - <p>A driver monitor for unload will eventually result + ever loaded.</p> + <p>A driver monitor for unload eventually results in one of the following messages being sent:</p> <taglist> - <tag><em>{'DOWN', reference(), driver, Name, unloaded}</em></tag> + <tag><c>{'DOWN', reference(), driver, Name, unloaded}</c></tag> <item> - <p>The driver instance monitored is now - unloaded. As the unload might have been due to a - <c>reload/2</c> request, the driver might once + <p>The monitored driver instance is now + unloaded. As the unload can be a result of a + <c>reload/2</c> request, the driver can once again have been loaded when this message arrives.</p> </item> - <tag><em>{'UP', reference(), driver, Name, unload_cancelled}</em></tag> + <tag><c>{'UP', reference(), driver, Name, unload_cancelled}</c></tag> <item> - <p>This message will be sent if unloading was + <p>This message is sent if unloading was expected, but while the driver was waiting for - all ports to get closed, a new <seealso marker="#users">user</seealso> of the driver - appeared and the unloading was cancelled.</p> - <p>This message appears when an <c>{ok, pending_driver}</c>) was returned from <seealso marker="#try_unload/2">try_unload/2</seealso>) - for the last <seealso marker="#users">user</seealso> of the driver and - then a <c>{ok, already_loaded}</c> is returned - from a call to <seealso marker="#try_load/3">try_load/3</seealso>.</p> - <p>If one wants to <em>really</em> monitor when the - driver gets unloaded, this message will distort - the picture, no unloading was really done. - The <c>unloaded_only</c> option creates a monitor - similar to an <c>unloaded</c> monitor, but does - never result in this message.</p> + all ports to get closed, a new + <seealso marker="#users">user</seealso> of the driver + appeared, and the unloading was cancelled.</p> + <p>This message appears if <c>{ok, pending_driver}</c> + was returned from + <seealso marker="#try_unload/2"><c>try_unload/2</c></seealso> + for the last <seealso marker="#users">user</seealso> + of the driver, and then <c>{ok, already_loaded}</c> is returned + from a call to + <seealso marker="#try_load/3"><c>try_load/3</c></seealso>.</p> + <p>If one <em>really</em> wants to monitor when the + driver gets unloaded, this message distorts + the picture, because no unloading was done. + Option <c>unloaded_only</c> creates a monitor + similar to an <c>unloaded</c> monitor, but + never results in this message.</p> </item> - <tag><em>{'UP', reference(), driver, Name, permanent}</em></tag> + <tag><c>{'UP', reference(), driver, Name, permanent}</c></tag> <item> - <p>This message will be sent if unloading was + <p>This message is sent if unloading was expected, but the driver made itself - permanent prior to unloading. It will also be + permanent before unloading. It is also sent if trying to monitor a permanent or - statically linked in driver.</p> + statically linked-in driver.</p> </item> </taglist> </item> - <tag><em>unloaded_only</em></tag> + <tag><c>unloaded_only</c></tag> <item> <p>A monitor created as <c>unloaded_only</c> behaves - exactly as one created as <c>unloaded</c> with the - exception that the <c>{'UP', reference(), driver, Name, unload_cancelled}</c> message will never be - sent, but the monitor instead persists until the - driver <em>really</em> gets unloaded.</p> + exactly as one created as <c>unloaded</c> + except that the + <c>{'UP', reference(), driver, Name, unload_cancelled}</c> + message is never sent, but the monitor instead persists until + the driver <em>really</em> gets unloaded.</p> </item> </taglist> </item> </taglist> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> + parameters are not specified as described here.</p> </desc> </func> <func> <name name="reload" arity="2"/> - <fsummary>Replace a driver</fsummary> + <fsummary>Replace a driver.</fsummary> <desc> <p>Reloads the driver named <c><anno>Name</anno></c> from a possibly - different <c><anno>Path</anno></c> than was previously used. This - function is used in the code change <seealso marker="#scenarios">scenario</seealso> described in the + different <c><anno>Path</anno></c> than previously used. This + function is used in the code change + <seealso marker="#scenarios"><c>scenario</c></seealso> described in the introduction.</p> <p>If there are other <seealso marker="#users">users</seealso> - of this driver, the function will return <c>{error, pending_process}</c>, but if there are no more users, the - function call will hang until all open ports are closed.</p> + of this driver, the function returns <c>{error, pending_process}</c>, + but if there are no other users, the function call hangs until all + open ports are closed.</p> <note> - <p>Avoid mixing - several <seealso marker="#users">users</seealso> - with driver reload requests.</p> - </note> - <p>If one wants to avoid hanging on open ports, one should use - the <seealso marker="#try_load/3">try_load/3</seealso> - function instead.</p> - <p>The <c><anno>Name</anno></c> and <c><anno>Path</anno></c> parameters have exactly the - same meaning as when calling the plain <seealso marker="#load/2">load/2</seealso> function.</p> - <note> - <p>Avoid mixing - several <seealso marker="#users">users</seealso> - with driver reload requests.</p> + <p>Avoid mixing multiple + <seealso marker="#users">users</seealso> + with driver reload requests.</p> </note> + <p>To avoid hanging on open ports, use function + <seealso marker="#try_load/3"><c>try_load/3</c></seealso> + instead.</p> + <p>The <c><anno>Name</anno></c> and <c><anno>Path</anno></c> parameters + have exactly the same meaning as when calling the plain function + <seealso marker="#load/2"><c>load/2</c></seealso>.</p> + <p>On success, the function returns <c>ok</c>. On - failure, the function returns an opaque error, with the - exception of the <c>pending_process</c> error described - above. The opaque errors are to be translated into human - readable form by the <seealso marker="#format_error/1">format_error/1</seealso> function.</p> - <p>For more control over the error handling, again use the - <seealso marker="#try_load/3">try_load/3</seealso> + failure, the function returns an opaque error, + except the <c>pending_process</c> error described + earlier. The opaque errors are to be translated into human + readable form by function + <seealso marker="#format_error/1"><c>format_error/1</c></seealso>.</p> + <p>For more control over the error handling, use the + <seealso marker="#try_load/3"><c>try_load/3</c></seealso> interface instead.</p> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> + parameters are not specified as described here.</p> </desc> </func> <func> <name name="reload_driver" arity="2"/> - <fsummary>Replace a driver</fsummary> + <fsummary>Replace a driver.</fsummary> <desc> - <p>Works exactly as <seealso marker="#reload/2">reload/2</seealso>, but for drivers - loaded with the <seealso marker="#load_driver/2">load_driver/2</seealso> interface. </p> - <p>As this interface implies that ports are being killed when - the last user disappears, the function wont hang waiting for + <p>Works exactly as <seealso marker="#reload/2"><c>reload/2</c></seealso>, + but for drivers loaded with the + <seealso marker="#load_driver/2"><c>load_driver/2</c></seealso> interface.</p> + <p>As this interface implies that ports are killed when + the last user disappears, the function does not hang waiting for ports to get closed.</p> - <p>For further details, see the <seealso marker="#scenarios">scenarios</seealso> in the module - description and refer to the <seealso marker="#reload/2">reload/2</seealso> function description.</p> + <p>For more details, see + <seealso marker="#scenarios"><c>scenarios</c></seealso> in this module + description and the function description for + <seealso marker="#reload/2"><c>reload/2</c></seealso>.</p> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> + parameters are not specified as described here.</p> </desc> </func> <func> <name name="try_load" arity="3"/> - <fsummary>Load a driver</fsummary> + <fsummary>Load a driver.</fsummary> <desc> - <p>This function provides more control than the + <p>Provides more control than the <c>load/2</c>/<c>reload/2</c> and <c>load_driver/2</c>/<c>reload_driver/2</c> interfaces. It - will never wait for completion of other operations related - to the driver, but immediately return the status of the - driver as either:</p> + never waits for completion of other operations related + to the driver, but immediately returns the status of the + driver as one of the following:</p> <taglist> - <tag><em>{ok, loaded}</em></tag> + <tag><c>{ok, loaded}</c></tag> <item> - <p>The driver was actually loaded and is immediately - usable.</p> + <p>The driver was loaded and is immediately usable.</p> </item> - <tag><em>{ok, already_loaded}</em></tag> + <tag><c>{ok, already_loaded}</c></tag> <item> <p>The driver was already loaded by another process - and/or is in use by a living port. The load by you is + or is in use by a living port, or both. The load by you is registered and a corresponding <c>try_unload</c> is expected sometime in the future.</p> </item> - <tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, reference()}</em></tag> + <tag><c>{ok, pending_driver}</c>or <c>{ok, pending_driver, reference()}</c></tag> <item> <p>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 - <em>mostly</em> happen when the + delayed because an earlier instance of the + driver is still waiting to get unloaded (open + ports use it). Still, unload is expected when you are + done with the driver. This return value + <em>mostly</em> occurs when options <c>{reload,pending_driver}</c> or - <c>{reload,pending}</c> options are used, but - <em>can</em> happen when another <seealso marker="#users">user</seealso> is unloading a driver in - parallel and the <c>kill_ports</c> driver option is - set. In other words, this return value will always need - to be handled!</p> + <c>{reload,pending}</c> are used, but + <em>can</em> occur when another + <seealso marker="#users">user</seealso> is unloading a + driver in parallel and driver option <c>kill_ports</c> is set. + In other words, this return value always needs + to be handled.</p> </item> - <tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, reference()}</em></tag> + <tag><c>{ok, pending_process}</c>or <c>{ok, pending_process, reference()}</c></tag> <item> <p>The load request is registered, but the loading is - delayed due to the fact that an earlier instance of the + delayed because an earlier instance of the driver is still waiting to get unloaded by another <seealso marker="#users">user</seealso> (not only by a port, in which case <c>{ok,pending_driver}</c> would have been returned). Still, unload is expected when you - are done with the driver. This return value will - <em>only</em> happen when the <c>{reload,pending}</c> - option is used.</p> + are done with the driver. This return value + <em>only</em> occurs when option <c>{reload,pending}</c> + is used.</p> </item> </taglist> <p>When the function returns <c>{ok, pending_driver}</c> or - <c>{ok, pending_process}</c>, one might want to get information - about when the driver is <em>actually</em> loaded. This can - be achieved by using the <c>{monitor, <anno>MonitorOption</anno>}</c> option.</p> - <p>When monitoring is requested, and a corresponding <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c> would be - returned, the function will instead return a tuple <c>{ok, <anno>PendingStatus</anno>, reference()}</c> 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 <seealso marker="#monitor/2">monitor/2</seealso> - function description. </p> + <c>{ok, pending_process}</c>, one can get information + about when the driver is <em>actually</em> loaded by using + option <c>{monitor, <anno>MonitorOption</anno>}</c>.</p> + <p>When monitoring is requested, and a corresponding + <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c> would + be returned, the function instead returns a tuple + <c>{ok, <anno>PendingStatus</anno>, reference()}</c> + and the process then gets a monitor message later, when the + driver gets loaded. The monitor message to expect is described in + the function description of + <seealso marker="#monitor/2"><c>monitor/2</c></seealso>.</p> <note> - <p>Note that in case of loading, monitoring can - <em>not</em> only get triggered by using the <c>{reload, <anno>ReloadOption</anno>}</c> option, but also in special cases where - the load-error is transient, why <c>{monitor, pending_driver}</c> should be used under basically - <em>all</em> real world circumstances!</p> + <p>In case of loading, monitoring can <em>not</em> only get + triggered by using option <c>{reload, <anno>ReloadOption</anno>}</c>, + but also in special cases where the load error is transient. Thus, + <c>{monitor, pending_driver}</c> is to be used under basically + <em>all</em> real world circumstances.</p> </note> <p>The function accepts the following parameters:</p> <taglist> - <tag><em><c><anno>Path</anno></c></em></tag> + <tag><c><anno>Path</anno></c></tag> <item> - <p>The filesystem path to the directory where the driver - object file is situated. The filename of the object file + <p>The file system path to the directory where the driver + object file is located. 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 - <c><anno>Path</anno></c> might be provided as an <em>iolist()</em>, + (used in parameter <c><anno>Name</anno></c>) and the driver must + identify itself with the same name. + <c><anno>Path</anno></c> can be provided as an <em>iolist()</em>, meaning it can be a list of other <c>iolist()</c>s, characters - (eight bit integers) or binaries, all to be flattened + (8-bit integers), or binaries, all to be flattened into a sequence of characters.</p> <p>The (possibly flattened) <c><anno>Path</anno></c> parameter must be - consistent throughout the system, a driver should, by + consistent throughout the system. A driver is to, by all <seealso marker="#users">users</seealso>, be loaded - using the same <em>literal</em><c><anno>Path</anno></c>. The - exception is when <em>reloading</em> is requested, in - which case the <c><anno>Path</anno></c> may be specified - differently. Note that all <seealso marker="#users">users</seealso> trying to load the - driver at a later time will need to use the <em>new</em><c><anno>Path</anno></c> if the <c><anno>Path</anno></c> is changed using a - <c>reload</c> option. This is yet another reason + using the same <em>literal</em> <c><anno>Path</anno></c>. + The exception is when <em>reloading</em> is requested, + in which case <c><anno>Path</anno></c> can be specified + differently. Notice that all + <seealso marker="#users">users</seealso> trying to load the + driver later need to use the + <em>new</em> <c><anno>Path</anno></c> if <c><anno>Path</anno></c> + is changed using a <c>reload</c> option. This is yet another reason to have <em>only one loader</em> of a driver one wants to - upgrade in a running system! </p> + upgrade in a running system.</p> </item> - <tag><em><c><anno>Name</anno></c></em></tag> + <tag><c><anno>Name</anno></c></tag> <item> - <p>The name parameter is the name of the driver to be used - in subsequent calls to <seealso marker="erts:erlang#open_port/2">open_port</seealso>. The - name can be specified either as an <c>iolist()</c> or - as an <c>atom()</c>. The name given when loading is used - to find the actual object file (with the - help of the <c><anno>Path</anno></c> and the system implied - extension suffix, i.e. <c>.so</c>). The name by which - the driver identifies itself must also be consistent - with this <c><anno>Name</anno></c> parameter, much as a beam-file's - module name much correspond to its filename.</p> + <p>This parameter is the name of the driver + to be used in subsequent calls to function + <seealso marker="erts:erlang#open_port/2"><c>erlang:open_port</c></seealso> + in <c>ERTS</c>. + The name can be specified as an <c>iolist()</c> or + an <c>atom()</c>. The name specified when loading is used + to find the object file (with the help of <c><anno>Path</anno></c> + and the system-implied extension suffix, that is, <c>.so</c>). + The name by which the driver identifies itself must also be consistent + with this <c><anno>Name</anno></c> parameter, much as + the module name of a Beam file much corresponds to its filename.</p> </item> - <tag><em><c><anno>OptionList</anno></c></em></tag> + <tag><c><anno>OptionList</anno></c></tag> <item> - <p>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 + <p>Some options can be specified to control the + loading operation. The options are specified as a list of + two-tuples. The tuples have the following values and meanings:</p> <taglist> - <tag><em>{driver_options, <c><anno>DriverOptionList</anno></c>}</em></tag> + <tag><c>{driver_options, <anno>DriverOptionList</anno>}</c></tag> <item> - <p>This option is to provide options that will change - its general behavior and will "stick" to the driver + <p>This is to provide options that changes + its general behavior and "sticks" to the driver throughout its lifespan.</p> - <p>The driver options for a given driver name need - always to be consistent, <em>even when the driver is reloaded</em>, meaning that they are as much a part - of the driver as the actual name.</p> - <p>Currently the only allowed driver option is + <p>The driver options for a specified driver name need + always to be consistent, <em>even when the driver is reloaded</em>, + meaning that they are as much a part of the driver as the name.</p> + <p>The only allowed driver option is <c>kill_ports</c>, which means that all ports opened - towards the driver are killed with the exit-reason + to the driver are killed with exit reason <c>driver_unloaded</c> when no process any longer has the driver loaded. This situation arises either - when the last <seealso marker="#users">user</seealso> calls <seealso marker="#try_unload/2">try_unload/2</seealso>, or - the last process having loaded the driver exits.</p> + when the last <seealso marker="#users">user</seealso> calls + <seealso marker="#try_unload/2"><c>try_unload/2</c></seealso>, or + when the last process having loaded the driver exits.</p> </item> - <tag><em>{monitor, <c><anno>MonitorOption</anno></c>}</em></tag> + <tag><c>{monitor, <anno>MonitorOption</anno>}</c></tag> <item> <p>A <c><anno>MonitorOption</anno></c> tells <c>try_load/3</c> to trigger a driver monitor under certain conditions. When the monitor is triggered, the - function will return a three-tuple <c>{ok, <anno>PendingStatus</anno>, reference()}</c>, where the <c>reference()</c> is - the monitor ref for the driver monitor.</p> - <p>Only one <c><anno>MonitorOption</anno></c> can be specified and - it is either the atom <c>pending</c>, which means - that a monitor should be created whenever a load - operation is delayed, and the atom - <c>pending_driver</c>, in which a monitor is - created whenever the operation is delayed due to - open ports towards an otherwise unused driver. The - <c>pending_driver</c> 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 <c><anno>MonitorOption</anno></c> as the <c><anno>ReloadOption</anno></c> - if present.</p> - <p>If reloading is not requested, it might still be - useful to specify the <c>monitor</c> option, as - forced unloads (<c>kill_ports</c> driver option or - the <c>kill_ports</c> option to <seealso marker="#try_unload/2">try_unload/2</seealso>) will - trigger a transient state where driver loading + function returns a three-tuple + <c>{ok, <anno>PendingStatus</anno>, reference()}</c>, where + <c>reference()</c> is the monitor reference for the driver monitor.</p> + <p>Only one <c><anno>MonitorOption</anno></c> can be specified. + It is one of the following:</p> + <list type="bulleted"> + <item> + <p>The atom <c>pending</c>, which means + that a monitor is to be created whenever a load + operation is delayed,</p> + </item> + <item> + <p>The atom <c>pending_driver</c>, in which a monitor + is created whenever the operation is delayed because + of open ports to an otherwise unused driver.</p> + </item> + </list> + <p>Option <c>pending_driver</c> 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 + <c><anno>MonitorOption</anno></c> as the + <c><anno>ReloadOption</anno></c>, if present.</p> + <p>If reloading is not requested, it can still be + useful to specify option <c>monitor</c>, as + forced unloads (driver option <c>kill_ports</c> or + option <c>kill_ports</c> to + <seealso marker="#try_unload/2"><c>try_unload/2</c></seealso>) + trigger a transient state where driver loading cannot be performed until all closing ports are - actually closed. So, as <c>try_unload</c> can, in - almost all situations, return <c>{ok, pending_driver}</c>, one should always specify at least - <c>{monitor, pending_driver}</c> in production - code (see the monitor discussion above). </p> + closed. Thus, as <c>try_unload</c> can, in + almost all situations, return <c>{ok, pending_driver}</c>, + always specify at least <c>{monitor, pending_driver}</c> + in production code (see the monitor discussion earlier).</p> </item> - <tag><em>{reload, <c><anno>ReloadOption</anno></c>}</em></tag> + <tag><c>{reload, <anno>ReloadOption</anno>}</c></tag> <item> - <p>This option is used when one wants to + <p>This option is used to <em>reload</em> a driver from disk, most often in a code upgrade scenario. Having a <c>reload</c> option - also implies that the <c><anno>Path</anno></c> parameter need - <em>not</em> be consistent with earlier loads of + also implies that parameter <c><anno>Path</anno></c> does + <em>not</em> need to be consistent with earlier loads of the driver.</p> - <p>To reload a driver, the process needs to have previously - loaded the driver, i.e there has to be an active <seealso marker="#users">user</seealso> of the driver in the process. </p> - <p>The <c>reload</c> option can be either the atom - <c>pending</c>, in which reloading is requested for - any driver and will be effectuated when <em>all</em> - 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 <seealso marker="#users">users</seealso> - having the driver loaded! - The option also triggers port-killing (if the - <c>kill_ports</c> 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 <seealso marker="#users">users</seealso>. The pending option is - seldom used as one does not want other <seealso marker="#users">users</seealso> to have loaded the - driver when code change is underway. </p> - <p>The more useful option is <c>pending_driver</c>, - which means that reloading will be queued if the - driver is <em>not</em> loaded by any other <seealso marker="#users">users</seealso>, but the driver has - opened ports, in which case <c>{ok, pending_driver}</c> will be returned (a - <c>monitor</c> option is of course recommended).</p> - <p>If the driver is unloaded (not present in the - system), the error code - <c>not_loaded</c> will be returned. The - <c>reload</c> option is intended for when the user + <p>To reload a driver, the process must have loaded the driver + before, that is, there must be an active + <seealso marker="#users">user</seealso> of the driver + in the process.</p> + <p>The <c>reload</c> option can be either of the following:</p> + <taglist> + <tag><c>pending</c></tag> + <item> + <p>With the atom <c>pending</c>, reloading is requested + for any driver and is effectuated when <em>all</em> + ports opened to the driver are closed. The driver + replacement in this case takes + place regardless if there are still + pending <seealso marker="#users">users</seealso> + having the driver loaded.</p> + <p>The option also triggers port-killing (if driver + option <c>kill_ports</c> is used) although + there are pending users, making it usable for forced + driver replacement, but laying much + responsibility on the driver + <seealso marker="#users">users</seealso>. + The pending option is seldom used as one does not want other + <seealso marker="#users">users</seealso> to have loaded + the driver when code change is underway.</p></item> + <tag><c>pending_driver</c></tag> + <item> + <p>This option is more useful. Here, reloading is queued + if the driver is <em>not</em> loaded by any other + <seealso marker="#users">users</seealso>, but the + driver has opened ports, in which case + <c>{ok, pending_driver}</c> is returned + (a <c>monitor</c> option is recommended).</p></item> + </taglist> + <p>If the driver is unloaded (not present in the system), + error code <c>not_loaded</c> is returned. Option + <c>reload</c> is intended for when the user has already loaded the driver in advance.</p> </item> </taglist> </item> </taglist> - <p>The function might return numerous errors, of which some - only can be returned given a certain combination of options.</p> - <p>A number of errors are opaque and can only be interpreted by - passing them to the <seealso marker="#format_error/1">format_error/1</seealso> function, + <p>The function can return numerous errors, some + can only be returned given a certain combination of options.</p> + <p>Some errors are opaque and can only be interpreted by + passing them to function + <seealso marker="#format_error/1"><c>format_error/1</c></seealso>, but some can be interpreted directly:</p> <taglist> - <tag><em>{error,linked_in_driver}</em></tag> + <tag><c>{error,linked_in_driver}</c></tag> <item> - <p>The driver with the specified name is an erlang - statically linked in driver, which cannot be manipulated + <p>The driver with the specified name is an Erlang + statically linked-in driver, which cannot be manipulated with this API.</p> </item> - <tag><em>{error,inconsistent}</em></tag> + <tag><c>{error,inconsistent}</c></tag> <item> - <p>The driver has already been loaded with either other - <c><anno>DriverOptionList</anno></c> or a different <em>literal</em><c>Path</c> argument.</p> - <p>This can happen even if a <c>reload</c> option is given, - if the <c>DriverOptionList</c> differ from the current.</p> + <p>The driver is already loaded with other + <c><anno>DriverOptionList</anno></c> or a different + <em>literal</em> <c>Path</c> argument.</p> + <p>This can occur even if a <c>reload</c> option is specified, + if <c>DriverOptionList</c> differs from the current.</p> </item> - <tag><em>{error, permanent}</em></tag> + <tag><c>{error, permanent}</c></tag> <item> <p>The driver has requested itself to be permanent, making - it behave like an erlang linked in driver and it can no + it behave like an Erlang linked-in driver and can no longer be manipulated with this API.</p> </item> - <tag><em>{error, pending_process}</em></tag> + <tag><c>{error, pending_process}</c></tag> <item> - <p>The driver is loaded by other <seealso marker="#users">users</seealso> when the <c>{reload, pending_driver}</c> option was given.</p> + <p>The driver is loaded by other + <seealso marker="#users">users</seealso> when + option <c>{reload, pending_driver}</c> was specified.</p> </item> - <tag><em>{error, pending_reload}</em></tag> + <tag><c>{error, pending_reload}</c></tag> <item> - <p>Driver reload is already requested by another <seealso marker="#users">user</seealso> when the <c>{reload, <anno>ReloadOption</anno>}</c> option was given.</p> + <p>Driver reload is already requested by another + <seealso marker="#users">user</seealso> when option + <c>{reload, <anno>ReloadOption</anno>}</c> was specified.</p> </item> - <tag><em>{error, not_loaded_by_this_process}</em></tag> + <tag><c>{error, not_loaded_by_this_process}</c></tag> <item> - <p>Appears when the <c>reload</c> option is given. The - driver <c><anno>Name</anno></c> is present in the system, but there is no - <seealso marker="#users">user</seealso> of it in this + <p>Appears when option <c>reload</c> is specified. The + driver <c><anno>Name</anno></c> is present in the system, but there + is no <seealso marker="#users">user</seealso> of it in this process.</p> </item> - <tag><em>{error, not_loaded}</em></tag> + <tag><c>{error, not_loaded}</c></tag> <item> - <p>Appears when the <c>reload</c> option is given. The + <p>Appears when option <c>reload</c> is specified. The driver <c><anno>Name</anno></c> is not in the system. Only drivers loaded by this process can be reloaded.</p> </item> </taglist> - <p>All other error codes are to be translated by the <seealso marker="#format_error/1">format_error/1</seealso> - function. Note that calls to <c>format_error</c> 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.</p> - <p>If the arguments or options are malformed, the function will - throw a <c>badarg</c> exception.</p> + <p>All other error codes are to be translated by function + <seealso marker="#format_error/1"><c>format_error/1</c></seealso>. + Notice that calls to <c>format_error</c> are to be + performed from the same running instance of the Erlang + virtual machine as the error is detected in, because of + system-dependent behavior concerning error values.</p> + <p>If the arguments or options are malformed, the function + throws a <c>badarg</c> exception.</p> </desc> </func> <func> <name name="try_unload" arity="2"/> - <fsummary>Unload a driver</fsummary> + <fsummary>Unload a driver.</fsummary> <desc> - <p>This is the low level function to unload (or decrement + <p>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 - <c>kill_ports</c> implicitly does, and it can trigger a - monitor either due to other <seealso marker="#users">users</seealso> still having the driver - loaded or that there are open ports using the driver.</p> + <c>kill_ports</c> implicitly does. Also, it can trigger a + monitor either because other + <seealso marker="#users">users</seealso> still have the driver + loaded or because open ports use the driver.</p> <p>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 <seealso marker="#users">user</seealso>) 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 <c>kill_ports</c> option set, or if - <c>kill_ports</c> was specified as an option to this - function, all pending ports using this driver will get - killed when unloading is done by the last <seealso marker="#users">user</seealso>. 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 <seealso marker="#users">user</seealso> (or even this user) loads the - driver again before the driver is actually unloaded, the - unloading will never take place.</p> - <p>To allow the <seealso marker="#users">user</seealso> that - <em>requests unloading</em> to wait for <em>actual unloading</em> to - take place, <c>monitor</c> triggers can be specified in much - the same way as when loading. As <seealso marker="#users">users</seealso> of this function however - seldom are interested in more than decrementing the - reference counts, monitoring is more seldom needed. If the - <c>kill_ports</c> 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 <c>pending_driver</c> case.</p> - <p>The possible monitor messages that can be expected are the - same as when using the <c>unloaded</c> option to the - <seealso marker="#monitor/2">monitor/2</seealso> function.</p> - <p>The function will return one of the following statuses upon + particular process (that is, this + <seealso marker="#users">user</seealso>) 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.</p> + <p>If the driver has option <c>kill_ports</c> set, or if + <c>kill_ports</c> is specified as an option to this + function, all pending ports using this driver are + killed when unloading is done by the last + <seealso marker="#users">user</seealso>. 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 + <seealso marker="#users">user</seealso> (or even this user) + loads the driver again before the driver is unloaded, the + unloading never takes place.</p> + <p>To allow the <seealso marker="#users">user</seealso> to + <em>request unloading</em> to wait for <em>actual unloading</em>, + <c>monitor</c> triggers can be specified in much the same way as + when loading. However, as <seealso marker="#users">users</seealso> + of this function seldom are interested in more than decrementing the + reference counts, monitoring is seldom needed.</p> + <note><p> If option <c>kill_ports</c> 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 <c>pending_driver</c> + case.</p></note> + <p>The possible monitor messages to expect are the + same as when using option <c>unloaded</c> to function + <seealso marker="#monitor/2"><c>monitor/2</c></seealso>.</p> + <p>The function returns one of the following statuses upon success:</p> <taglist> - <tag><em>{ok, unloaded}</em></tag> + <tag><c>{ok, unloaded}</c></tag> <item> <p>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.</p> <p>The driver can only be unloaded when there are no open - ports using it and there are no more <seealso marker="#users">users</seealso> requiring it to be + ports using it and no more + <seealso marker="#users">users</seealso> require it to be loaded.</p> </item> - <tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, reference()}</em></tag> + <tag><c>{ok, pending_driver}</c>or + <c>{ok, pending_driver, reference()}</c></tag> <item> - <p>This return value indicates that this call removed the - last <seealso marker="#users">user</seealso> from the + <p>Indicates that this call removed the last + <seealso marker="#users">user</seealso> from the driver, but there are still open ports using it. - When all ports are closed and no new <seealso marker="#users">users</seealso> have arrived, the driver - will actually be reloaded and the name and memory + When all ports are closed and no new + <seealso marker="#users">users</seealso> have arrived, + the driver is reloaded and the name and memory reclaimed.</p> - <p>This return value is valid even when the option - <c>kill_ports</c> 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.</p> + <p>This return value is valid even if option <c>kill_ports</c> + 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.</p> </item> - <tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, reference()}</em></tag> + <tag><c>{ok, pending_process}</c>or + <c>{ok, pending_process, reference()}</c></tag> <item> - <p>The unload request is registered, but there are still - other <seealso marker="#users">users</seealso> holding - the driver. Note that the term <c>pending_process</c> - might refer to the running process, there might be more + <p>The unload request is registered, but + other <seealso marker="#users">users</seealso> still hold + the driver. Notice that the term <c>pending_process</c> + can refer to the running process; there can be more than one <seealso marker="#users">user</seealso> in the same process.</p> - <p>This is a normal, healthy return value if the call was + <p>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 <seealso marker="#scenarios">scenario</seealso> + further use of the driver. It is the most + common return value in the most common + <seealso marker="#scenarios"><c>scenario</c></seealso> described in the introduction.</p> </item> </taglist> <p>The function accepts the following parameters:</p> <taglist> - <tag><em><c><anno>Name</anno></c></em></tag> + <tag><c><anno>Name</anno></c></tag> <item> - <p>The name parameter is the name of the driver to be - unloaded. The name can be specified either as an - <c>iolist()</c> or as an <c>atom()</c>. </p> + <p><c><anno>Name</anno></c> is the name of the + driver to be unloaded. The name can be specified as an + <c>iolist()</c> or as an <c>atom()</c>.</p> </item> - <tag><em><c><anno>OptionList</anno></c></em></tag> + <tag><c><anno>OptionList</anno></c></tag> <item> - <p>The <c><anno>OptionList</anno></c> argument can be used to specify - certain behavior regarding ports as well as triggering + <p>Argument <c><anno>OptionList</anno></c> can be used to specify + certain behavior regarding ports and triggering monitors under certain conditions:</p> <taglist> - <tag><em>kill_ports</em></tag> + <tag><c>kill_ports</c></tag> <item> - <p>Force killing of all ports opened using this driver, - with the exit reason <c>driver_unloaded</c>, if you are - the <em>last</em><seealso marker="#users">user</seealso> of the driver.</p> - <p>If there are other <seealso marker="#users">users</seealso> having the driver - loaded, this option will have no effect.</p> - <p>If one wants the consistent behavior of killing ports + <p>Forces killing of all ports opened using this driver, + with exit reason <c>driver_unloaded</c>, if you are + the <em>last</em> <seealso marker="#users">user</seealso> + of the driver.</p> + <p>If other <seealso marker="#users">users</seealso> + have the driver loaded, this option has no effect.</p> + <p>To get the consistent behavior of killing ports when the last <seealso marker="#users">user</seealso> - unloads, one should use the driver option + unloads, use driver option <c>kill_ports</c> when loading the driver instead.</p> </item> - <tag><em>{monitor, <c><anno>MonitorOption</anno></c>}</em></tag> + <tag><c>{monitor, <anno>MonitorOption</anno>}</c></tag> <item> - <p>This option creates a driver monitor if the condition - given in <c><anno>MonitorOption</anno></c> is true. The valid + <p>Creates a driver monitor if the condition + specified in <c><anno>MonitorOption</anno></c> is true. The valid options are:</p> <taglist> - <tag><em>pending_driver</em></tag> + <tag><c>pending_driver</c></tag> <item> - <p>Create a driver monitor if the return value is to + <p>Creates a driver monitor if the return value is to be <c>{ok, pending_driver}</c>.</p> </item> - <tag><em>pending</em></tag> + <tag><c>pending</c></tag> <item> - <p>Create a monitor if the return value will be either + <p>Creates a monitor if the return value is <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c>.</p> </item> </taglist> - <p>The <c>pending_driver</c> <c><anno>MonitorOption</anno></c> 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 <c>kill_ports</c> option is used or the - driver may have been loaded with the <c>kill_ports</c> - driver option.</p> - <p>By using the monitor-triggers in the call to - <c>try_unload</c> 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 - <c>erl_ddll:monitor/2</c> separately.</p> + <p>The <c>pending_driver</c> <c><anno>MonitorOption</anno></c> is + by far the most useful. It must be used to ensure that the + driver really is unloaded and the ports closed + whenever option <c>kill_ports</c> is used, or the + driver can have been loaded with driver option + <c>kill_ports</c>.</p> + <p>Using the monitor triggers in the call to + <c>try_unload</c> 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 <c>monitor/2</c> is called + separately.</p> </item> </taglist> </item> </taglist> - <p>The function may return several error conditions, of which - all are well specified (no opaque values):</p> + <p>The function can return the following error conditions, + all well specified (no opaque values):</p> <taglist> - <tag><em>{error, linked_in_driver}</em></tag> + <tag><c>{error, linked_in_driver}</c></tag> <item> - <p>You were trying to unload an erlang statically linked in + <p>You were trying to unload an Erlang statically linked-in driver, which cannot be manipulated with this interface (and cannot be unloaded at all).</p> </item> - <tag><em>{error, not_loaded}</em></tag> + <tag><c>{error, not_loaded}</c></tag> <item> <p>The driver <c><anno>Name</anno></c> is not present in the system.</p> </item> - <tag><em>{error, not_loaded_by_this_process}</em></tag> + <tag><c>{error, not_loaded_by_this_process}</c></tag> <item> <p>The driver <c><anno>Name</anno></c> is present in the system, but there is no <seealso marker="#users">user</seealso> of it in this process. </p> <p>As a special case, drivers can be unloaded from - processes that has done no corresponding call to - <c>try_load/3</c> if, and only if, there are <em>no users of the driver at all</em>, which may happen if the + processes that have done no corresponding call to + <c>try_load/3</c> if, and only if, there are + <em>no users of the driver at all</em>, which can occur if the process containing the last user dies.</p> </item> - <tag><em>{error, permanent}</em></tag> + <tag><c>{error, permanent}</c></tag> <item> <p>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).</p> + like a statically linked-in driver).</p> </item> </taglist> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> + parameters are not specified as described here.</p> </desc> </func> <func> <name name="unload" arity="1"/> - <fsummary>Unload a driver</fsummary> + <fsummary>Unload a driver.</fsummary> <desc> <p>Unloads, or at least dereferences the driver named - <c><anno>Name</anno></c>. If the caller is the last <seealso marker="#users">user</seealso> 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 <seealso marker="#users">users</seealso>.</p> - <p>If there are other <seealso marker="#users">users</seealso> 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 <seealso marker="#scenarios">description</seealso> in the beginning - of this document. </p> + <c><anno>Name</anno></c>. If the caller is the last + <seealso marker="#users">user</seealso> 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 + <seealso marker="#users">users</seealso> remain.</p> + <p>If there are other <seealso marker="#users">users</seealso> + of the driver, the reference counts of the driver is merely decreased, + so that the caller is no longer considered a + <seealso marker="#users">user</seealso> of the driver. For use + scenarios, see the <seealso marker="#scenarios"><c>description</c></seealso> + in the beginning of this module.</p> <p>The <c><anno>ErrorDesc</anno></c> returned is an opaque value to be - passed further on to the <seealso marker="#format_error/1">format_error/1</seealso> - function. For more control over the operation, use the - <seealso marker="#try_unload/2">try_unload/2</seealso> + passed further on to function + <seealso marker="#format_error/1"><c>format_error/1</c></seealso>. + For more control over the operation, use the + <seealso marker="#try_unload/2"><c>try_unload/2</c></seealso> interface.</p> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> + parameters are not specified as described here.</p> </desc> </func> <func> <name name="unload_driver" arity="1"/> - <fsummary>Unload a driver</fsummary> + <fsummary>Unload a driver.</fsummary> <desc> <p>Unloads, or at least dereferences the driver named - <c><anno>Name</anno></c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, all - remaining open ports using the driver will get killed with - the reason <c>driver_unloaded</c> and the driver will - eventually get unloaded.</p> + <c><anno>Name</anno></c>. If the caller is the last + <seealso marker="#users">user</seealso> of the driver, all + remaining open ports using the driver are killed with + reason <c>driver_unloaded</c> and the driver + eventually gets unloaded.</p> <p>If there are other <seealso marker="#users">users</seealso> of the driver, the reference counts of the driver is merely decreased, so that the caller is no longer considered a <seealso marker="#users">user</seealso>. For - usage scenarios, see the <seealso marker="#scenarios">description</seealso> in the beginning - of this document.</p> + use scenarios, see the + <seealso marker="#scenarios"><c>description</c></seealso> in the + beginning of this module.</p> <p>The <c><anno>ErrorDesc</anno></c> returned is an opaque value to be - passed further on to the <seealso marker="#format_error/1">format_error/1</seealso> - function. For more control over the operation, use the - <seealso marker="#try_unload/2">try_unload/2</seealso> + passed further on to function + <seealso marker="#format_error/1"><c>format_error/1</c></seealso>. + For more control over the operation, use the + <seealso marker="#try_unload/2"><c>try_unload/2</c></seealso> interface.</p> <p>The function throws a <c>badarg</c> exception if the - parameters are not given as described above. </p> - </desc> - </func> - <func> - <name name="loaded_drivers" arity="0"/> - <fsummary>List loaded drivers</fsummary> - <desc> - <p>Returns a list of all the available drivers, both - (statically) linked-in and dynamically loaded ones.</p> - <p>The driver names are returned as a list of strings rather - than a list of atoms for historical reasons.</p> - <p>More information about drivers can be obtained using one of - the <seealso marker="#info/0">info</seealso> functions.</p> - </desc> - </func> - <func> - <name name="format_error" arity="1"/> - <fsummary>Format an error descriptor</fsummary> - <desc> - <p>Takes an <c><anno>ErrorDesc</anno></c> returned by load, unload or - reload functions and returns a string which - describes the error or warning.</p> - <note> - <p>Due to peculiarities in the dynamic loading interfaces on - different platform, the returned string is only guaranteed - to describe the correct error <em>if format_error/1 is called in the same instance of the erlang virtual machine as the error appeared in</em> (meaning the same operating - system process)!</p> - </note> + parameters are not specified as described here.</p> </desc> </func> </funcs> - <section> - <title>SEE ALSO</title> - <p>erl_driver(4), driver_entry(4)</p> + <title>See Also</title> + <p><seealso marker="erts:erl_driver"><c>erts:erl_driver(4)</c></seealso>, + <seealso marker="erts:driver_entry"><c>erts:driver_entry(4)</c></seealso></p> </section> </erlref> - |