aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/erl_ddll.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2011-05-13 13:59:45 +0200
committerHans Bolinder <[email protected]>2011-05-13 13:59:45 +0200
commit8c3a2a93b6b60253faa8397e5a02206b882b811f (patch)
treeb4b2ee3d8fb2729158305fdcdf3427e1537067f0 /lib/kernel/doc/src/erl_ddll.xml
parent897c1066e6c06285b1854b5af5c70dba0fd4f0ed (diff)
parent5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 (diff)
downloadotp-8c3a2a93b6b60253faa8397e5a02206b882b811f.tar.gz
otp-8c3a2a93b6b60253faa8397e5a02206b882b811f.tar.bz2
otp-8c3a2a93b6b60253faa8397e5a02206b882b811f.zip
Merge branch 'hb/kernel/doc_specs/OTP-9272' into dev
* hb/kernel/doc_specs/OTP-9272: Use Erlang specs and types for documentation
Diffstat (limited to 'lib/kernel/doc/src/erl_ddll.xml')
-rw-r--r--lib/kernel/doc/src/erl_ddll.xml129
1 files changed, 46 insertions, 83 deletions
diff --git a/lib/kernel/doc/src/erl_ddll.xml b/lib/kernel/doc/src/erl_ddll.xml
index 9a62b45d63..f9514dda2f 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>2010</year>
+ <year>1997</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -172,6 +172,14 @@
</item>
</taglist>
</description>
+ <datatypes>
+ <datatype>
+ <name name="driver"/>
+ </datatype>
+ <datatype>
+ <name name="path"/>
+ </datatype>
+ </datatypes>
<funcs>
<func>
<name>demonitor(MonitorRef) -> ok</name>
@@ -189,37 +197,21 @@
</desc>
</func>
<func>
- <name>info() -> AllInfoList</name>
+ <name name="info" arity="0"/>
<fsummary>Retrieve information about all drivers</fsummary>
- <type>
- <v>AllInfoList = [ DriverInfo ]</v>
- <v>DriverInfo = {DriverName, InfoList}</v>
- <v>DriverName = string()</v>
- <v>InfoList = [ InfoItem ]</v>
- <v>InfoItem = {Tag, Value}</v>
- <v>Tag = atom()</v>
- <v>Value = term()</v>
- </type>
<desc>
- <p>Returns a list of tuples <c>{DriverName, InfoList}</c>, where
- <c>InfoList</c> is the result of calling <seealso marker="#info/1">info/1</seealso> for that
- <c>DriverName</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">info/1</seealso> for that
+ <c><anno>DriverName</anno></c>. Only dynamically linked in drivers are
included in the list.</p>
</desc>
</func>
<func>
- <name>info(Name) -> InfoList</name>
+ <name name="info" arity="1"/>
<fsummary>Retrieve information about one driver</fsummary>
- <type>
- <v>Name = string() | atom()</v>
- <v>InfoList = [ InfoItem ]</v>
- <v>InfoItem = {Tag, Value}</v>
- <v>Tag = atom()</v>
- <v>Value = term()</v>
- </type>
<desc>
- <p>Returns a list of tuples <c>{Tag, Value}</c>, where
- <c>Tag</c> is the information item and <c>Value</c> is the result
+ <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>
@@ -305,22 +297,18 @@
</desc>
</func>
<func>
- <name>load(Path, Name) -> ok | {error, ErrorDesc}</name>
+ <name name="load" arity="2"/>
<fsummary>Load a driver</fsummary>
- <type>
- <v>Path = Name = string() | atom()</v>
- <v>ErrorDesc = term()</v>
- </type>
<desc>
- <p>Loads and links the dynamic driver <c>Name</c>. <c>Path</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>Name</c> must be a sharable object/dynamic library. Two
- drivers with different <c>Path</c> parameters cannot be
- loaded under the same name. The <c>Name</c> is a string or
+ <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
atom containing at least one character.</p>
- <p>The <c>Name</c> given should correspond to the filename
+ <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>Path</c>, but <em>without</em> the
+ 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
the driver initialization routine must correspond with the
filename, in much the same way as erlang module names
@@ -328,14 +316,14 @@
<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>Path</c> is the same) and <c>ok</c> is
+ (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
loading/unloading in the introduction.</p>
<p>If more than one process tries to load an already loaded
- driver withe the same <c>Path</c>, or if the same process
+ 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
<c>load/2</c> calls, so that a corresponding number of
@@ -349,16 +337,16 @@
several drivers with the same name but with different
<c>Path</c> parameters.</p>
<note>
- <p>Note especially that the <c>Path</c> is interpreted
+ <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>Path</c> string, even
+ 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
links).</p>
</note>
<p>On success, the function returns <c>ok</c>. On
- failure, the return value is <c>{error,ErrorDesc}</c>,
- where <c>ErrorDesc</c> is an opaque term to be
+ 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
@@ -369,20 +357,16 @@
</desc>
</func>
<func>
- <name>load_driver(Path, Name) -> ok | {error, ErrorDesc}</name>
+ <name name="load_driver" arity="2"/>
<fsummary>Load a driver</fsummary>
- <type>
- <v>Path = Name = string() | atom()</v>
- <v>ErrorDesc = term()</v>
- </type>
<desc>
<p>Works essentially as <c>load/2</c>, but will load the driver
- with options other options. All ports that are using the
+ 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
+ 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>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
@@ -551,16 +535,11 @@
</desc>
</func>
<func>
- <name>reload(Path, Name) -> ok | {error, ErrorDesc}</name>
+ <name name="reload" arity="2"/>
<fsummary>Replace a driver</fsummary>
- <type>
- <v>Path = Name = string() | atom()</v>
- <v>ErrorDesc = pending_process | OpaqueError</v>
- <v>OpaqueError = term()</v>
- </type>
<desc>
- <p>Reloads the driver named <c>Name</c> from a possibly
- different <c>Path</c> than was previously used. This
+ <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
introduction.</p>
<p>If there are other <seealso marker="#users">users</seealso>
@@ -574,7 +553,7 @@
<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>Name</c> and <c>Path</c> parameters have exactly the
+ <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
@@ -594,13 +573,8 @@
</desc>
</func>
<func>
- <name>reload_driver(Path, Name) -> ok | {error, ErrorDesc}</name>
+ <name name="reload_driver" arity="2"/>
<fsummary>Replace a driver</fsummary>
- <type>
- <v>Path = Name = string() | atom()</v>
- <v>ErrorDesc = pending_process | OpaqueError</v>
- <v>OpaqueError = term()</v>
- </type>
<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>
@@ -1066,15 +1040,11 @@
</desc>
</func>
<func>
- <name>unload(Name) -> ok | {error, ErrorDesc}</name>
+ <name name="unload" arity="1"/>
<fsummary>Unload a driver</fsummary>
- <type>
- <v>Name = string() | atom()</v>
- <v>ErrorDesc = term()</v>
- </type>
<desc>
<p>Unloads, or at least dereferences the driver named
- <c>Name</c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, and there
+ <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
@@ -1084,7 +1054,7 @@
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>
- <p>The <c>ErrorDesc</c> returned is an opaque value to be
+ <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>
@@ -1094,15 +1064,11 @@
</desc>
</func>
<func>
- <name>unload_driver(Name) -> ok | {error, ErrorDesc}</name>
+ <name name="unload_driver" arity="1"/>
<fsummary>Unload a driver</fsummary>
- <type>
- <v>Name = string() | atom()</v>
- <v>ErrorDesc = term()</v>
- </type>
<desc>
<p>Unloads, or at least dereferences the driver named
- <c>Name</c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, all
+ <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>
@@ -1112,7 +1078,7 @@
<seealso marker="#users">user</seealso>. For
usage scenarios, see the <seealso marker="#scenarios">description</seealso> in the beginning
of this document.</p>
- <p>The <c>ErrorDesc</c> returned is an opaque value to be
+ <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>
@@ -1125,7 +1091,7 @@
<name>loaded_drivers() -> {ok, Drivers}</name>
<fsummary>List loaded drivers</fsummary>
<type>
- <v>Drivers = [Driver()]</v>
+ <v>Drivers = [Driver]</v>
<v>Driver = string()</v>
</type>
<desc>
@@ -1138,13 +1104,10 @@
</desc>
</func>
<func>
- <name>format_error(ErrorDesc) -> string()</name>
+ <name name="format_error" arity="1"/>
<fsummary>Format an error descriptor</fsummary>
- <type>
- <v>ErrorDesc -- see below</v>
- </type>
<desc>
- <p>Takes an <c>ErrorDesc</c> returned by load, unload or
+ <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>