From 5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 16:01:56 +0200 Subject: Use Erlang specs and types for documentation --- lib/kernel/doc/src/erl_ddll.xml | 129 ++++++++++++++-------------------------- 1 file changed, 46 insertions(+), 83 deletions(-) (limited to 'lib/kernel/doc/src/erl_ddll.xml') 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 @@
- 19972010 + 19972011 Ericsson AB. All Rights Reserved. @@ -172,6 +172,14 @@ + + + + + + + + demonitor(MonitorRef) -> ok @@ -189,37 +197,21 @@ - info() -> AllInfoList + Retrieve information about all drivers - - AllInfoList = [ DriverInfo ] - DriverInfo = {DriverName, InfoList} - DriverName = string() - InfoList = [ InfoItem ] - InfoItem = {Tag, Value} - Tag = atom() - Value = term() - -

Returns a list of tuples {DriverName, InfoList}, where - InfoList is the result of calling info/1 for that - DriverName. Only dynamically linked in drivers are +

Returns a list of tuples {DriverName, InfoList}, where + InfoList is the result of calling info/1 for that + DriverName. Only dynamically linked in drivers are included in the list.

 - info(Name) -> InfoList + Retrieve information about one driver - - Name = string() | atom() - InfoList = [ InfoItem ] - InfoItem = {Tag, Value} - Tag = atom() - Value = term() - -

Returns a list of tuples {Tag, Value}, where - Tag is the information item and Value is the result +

Returns a list of tuples {Tag, Value}, where + Tag is the information item and Value is the result of calling info/2 with this driver name and this tag. The result being a tuple list containing all information available about a driver.

@@ -305,22 +297,18 @@ - load(Path, Name) -> ok | {error, ErrorDesc} + Load a driver - - Path = Name = string() | atom() - ErrorDesc = term() - -

Loads and links the dynamic driver Name. Path +

Loads and links the dynamic driver Name. Path is a file path to the directory containing the driver. - Name must be a sharable object/dynamic library. Two - drivers with different Path parameters cannot be - loaded under the same name. The Name is a string or + Name must be a sharable object/dynamic library. Two + drivers with different Path parameters cannot be + loaded under the same name. The Name is a string or atom containing at least one character.

-

The Name given should correspond to the filename +

The Name given should correspond to the filename of the actual dynamically loadable object file residing in - the directory given as Path, but without the + the directory given as Path, but without the extension (i.e. .so). The driver name provided in the driver initialization routine must correspond with the filename, in much the same way as erlang module names @@ -328,14 +316,14 @@

If the driver has been previously unloaded, but is still present due to open ports against it, a call to load/2 will stop the unloading and keep the driver - (as long as the Path is the same) and ok is + (as long as the Path is the same) and ok is returned. If one actually wants the object code to be reloaded, one uses reload/2 or the low-level interface try_load/3 instead. Please refer to the description of different scenarios for loading/unloading in the introduction.

If more than one process tries to load an already loaded - driver withe the same Path, or if the same process + driver withe the same Path, or if the same process tries to load it several times, the function will return ok. The emulator will keep track of the load/2 calls, so that a corresponding number of @@ -349,16 +337,16 @@ several drivers with the same name but with different Path parameters.

-

Note especially that the Path is interpreted +

Note especially that the Path is interpreted literally, so that all loaders of the same driver needs to - give the same literalPath string, even + give the same literalPath string, even though different paths might point out the same directory in the filesystem (due to use of relative paths and links).

On success, the function returns ok. On - failure, the return value is {error,ErrorDesc}, - where ErrorDesc is an opaque term to be + failure, the return value is {error,ErrorDesc}, + where ErrorDesc is an opaque term to be translated into human readable form by the format_error/1 function.

For more control over the error handling, again use the @@ -369,20 +357,16 @@ - load_driver(Path, Name) -> ok | {error, ErrorDesc} + Load a driver - - Path = Name = string() | atom() - ErrorDesc = term() -

Works essentially as load/2, but will load the driver - with options other options. All ports that are using the + with other options. All ports that are using the driver will get killed with the reason driver_unloaded when the driver is to be unloaded.

The number of loads and unloads by different users influence the actual loading and unloading of a driver file. The port killing will - therefore only happen when the lastuser unloads the driver, or the + therefore only happen when the last user unloads the driver, or the last process having loaded the driver exits.

This interface (or at least the name of the functions) is kept for backward compatibility. Using try_load/3 with @@ -551,16 +535,11 @@ - reload(Path, Name) -> ok | {error, ErrorDesc} + Replace a driver - - Path = Name = string() | atom() - ErrorDesc = pending_process | OpaqueError - OpaqueError = term() - -

Reloads the driver named Name from a possibly - different Path than was previously used. This +

Reloads the driver named Name from a possibly + different Path than was previously used. This function is used in the code change scenario described in the introduction.

If there are other users @@ -574,7 +553,7 @@

If one wants to avoid hanging on open ports, one should use the try_load/3 function instead.

-

The Name and Path parameters have exactly the +

The Name and Path parameters have exactly the same meaning as when calling the plain load/2 function.

Avoid mixing @@ -594,13 +573,8 @@ - reload_driver(Path, Name) -> ok | {error, ErrorDesc} + Replace a driver - - Path = Name = string() | atom() - ErrorDesc = pending_process | OpaqueError - OpaqueError = term() -

Works exactly as reload/2, but for drivers loaded with the load_driver/2 interface.

@@ -1066,15 +1040,11 @@ - unload(Name) -> ok | {error, ErrorDesc} + Unload a driver - - Name = string() | atom() - ErrorDesc = term() -

Unloads, or at least dereferences the driver named - Name. If the caller is the last user of the driver, and there + Name. If the caller is the last user of the driver, and there are no more open ports using the driver, the driver will actually get unloaded. In all other cases, actual unloading will be delayed until all ports are closed and there are no @@ -1084,7 +1054,7 @@ is no longer considered a user of the driver. For usage scenarios, see the description in the beginning of this document.

-

The ErrorDesc returned is an opaque value to be +

The ErrorDesc returned is an opaque value to be passed further on to the format_error/1 function. For more control over the operation, use the try_unload/2 @@ -1094,15 +1064,11 @@ - unload_driver(Name) -> ok | {error, ErrorDesc} + Unload a driver - - Name = string() | atom() - ErrorDesc = term() -

Unloads, or at least dereferences the driver named - Name. If the caller is the last user of the driver, all + Name. If the caller is the last user of the driver, all remaining open ports using the driver will get killed with the reason driver_unloaded and the driver will eventually get unloaded.

@@ -1112,7 +1078,7 @@ user. For usage scenarios, see the description in the beginning of this document.

-

The ErrorDesc returned is an opaque value to be +

The ErrorDesc returned is an opaque value to be passed further on to the format_error/1 function. For more control over the operation, use the try_unload/2 @@ -1125,7 +1091,7 @@ loaded_drivers() -> {ok, Drivers} List loaded drivers - Drivers = [Driver()] + Drivers = [Driver] Driver = string() @@ -1138,13 +1104,10 @@ - format_error(ErrorDesc) -> string() + Format an error descriptor - - ErrorDesc -- see below - -

Takes an ErrorDesc returned by load, unload or +

Takes an ErrorDesc returned by load, unload or reload functions and returns a string which describes the error or warning.

-- cgit v1.2.3