diff options
Diffstat (limited to 'erts/doc/src/erl_driver.xml')
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 4887 |
1 files changed, 2490 insertions, 2397 deletions
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 34dc8af238..5705100ab2 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2015</year> + <year>2001</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -21,7 +21,6 @@ limitations under the License. </legalnotice> - <title>erl_driver</title> <prepared>Jakob Cederlund</prepared> <responsible>Jakob Cederlund</responsible> @@ -33,519 +32,545 @@ <file>erl_driver.xml</file> </header> <lib>erl_driver</lib> - <libsummary>API functions for an Erlang driver</libsummary> + <libsummary>API functions for an Erlang driver.</libsummary> <description> <p>An Erlang driver is a library containing a set of native driver - callback functions that the Erlang VM calls when certain - events occur. There may be multiple instances of a driver, each + callback functions that the Erlang Virtual Machine calls when certain + events occur. There can be multiple instances of a driver, each instance is associated with an Erlang port.</p> + <marker id="WARNING"/> - <warning><p><em>Use this functionality with extreme care!</em></p> + <warning> + <p><em>Use this functionality with extreme care.</em></p> <p>A driver callback is executed as a direct extension of the - native code of the VM. Execution is not made in a safe environment. - The VM can <em>not</em> provide the same services as provided when - executing Erlang code, such as preemptive scheduling or memory - protection. If the driver callback function doesn't behave well, - the whole VM will misbehave.</p> - <list> - <item><p>A driver callback that crash will crash the whole VM.</p></item> - <item><p>An erroneously implemented driver callback might cause - a VM internal state inconsistency which may cause a crash of the VM, - or miscellaneous misbehaviors of the VM at any point after the call - to the driver callback.</p></item> - <item><p>A driver callback that do <seealso marker="#lengthy_work">lengthy - work</seealso> before returning will degrade responsiveness of the VM, - and may cause miscellaneous strange behaviors. Such strange behaviors - include, but are not limited to, extreme memory usage, and bad load - balancing between schedulers. Strange behaviors that might occur due - to lengthy work may also vary between OTP releases.</p></item> + native code of the VM. Execution is not made in a safe environment. + The VM <em>cannot</em> provide the same services as provided when + executing Erlang code, such as pre-emptive scheduling or memory + protection. If the driver callback function does not behave well, + the whole VM will misbehave.</p> + <list type="bulleted"> + <item> + <p>A driver callback that crash will crash the whole VM.</p> + </item> + <item> + <p>An erroneously implemented driver callback can cause a VM + internal state inconsistency, which can cause a crash of the VM, + or miscellaneous misbehaviors of the VM at any point after the + call to the driver callback.</p> + </item> + <item> + <p>A driver callback doing + <seealso marker="#lengthy_work">lengthy work</seealso> before + returning degrades responsiveness of the VM and can cause + miscellaneous strange behaviors. Such strange behaviors + include, but are not limited to, extreme memory usage and bad + load balancing between schedulers. Strange behaviors that can + occur because of lengthy work can also vary between Erlang/OTP + releases.</p> + </item> </list> - </warning> - <p>As of erts version 5.5.3 the driver interface has been extended - (see <seealso marker="driver_entry#extended_marker">extended marker</seealso>). - The extended interface introduce + </warning> + + <p>As from ERTS 5.5.3 the driver interface has been extended + (see <seealso marker="driver_entry#extended_marker"> + <c>extended marker</c></seealso>). The extended interface introduces <seealso marker="#version_management">version management</seealso>, - the possibility to pass capability flags - (see <seealso marker="driver_entry#driver_flags">driver flags</seealso>) - to the runtime system at driver initialization, and some new - driver API functions. </p> + the possibility to pass capability flags (see + <seealso marker="driver_entry#driver_flags"> + <c>driver_flags</c></seealso>) to the runtime system at driver + initialization, and some new driver API functions.</p> + <note> - <p>As of erts version 5.9 old drivers have to be recompiled - and have to use the extended interface. They also have to be - adjusted to the - <seealso marker="#rewrites_for_64_bits">64-bit capable driver interface. - </seealso> - </p> + <p>As from ERTS 5.9 old drivers must be recompiled + and use the extended interface. They must also be adjusted to the + <seealso marker="#rewrites_for_64_bits"> + 64-bit capable driver interface</seealso>.</p> </note> + <p>The driver calls back to the emulator, using the API functions declared in <c>erl_driver.h</c>. They are used for - outputting data from the driver, using timers, etc.</p> + outputting data from the driver, using timers, and so on.</p> + <p>Each driver instance is associated with a port. Every port has a port owner process. Communication with the port is normally done through the port owner process. Most of the functions take the <c>port</c> handle as an argument. This identifies the driver - instance. Note that this port handle must be stored by the driver, + instance. Notice that this port handle must be stored by the driver, it is not given when the driver is called from the emulator (see - <seealso marker="driver_entry#emulator">driver_entry</seealso>).</p> + <seealso marker="driver_entry#emulator"> + <c>driver_entry</c></seealso>).</p> + <p>Some of the functions take a parameter of type - <c>ErlDrvBinary</c>, a driver binary. It should be both + <c>ErlDrvBinary</c>, a driver binary. It is to be both allocated and freed by the caller. Using a binary directly avoids one extra copying of data.</p> + <p>Many of the output functions have a "header buffer", with <c>hbuf</c> and <c>hlen</c> parameters. This buffer is sent as a list before the binary (or list, depending on port mode) that is sent. This is convenient when matching on messages received from - the port. (Although in the latest versions of Erlang, there is - the binary syntax, that enables you to match on the beginning of - a binary.) - <marker id="smp_support"></marker> -</p> - <p>In the runtime system with SMP support, drivers are locked either - on driver level or port level (driver instance level). By default - driver level locking will be used, i.e., only one emulator thread + the port. (Although in the latest Erlang versions there is + the binary syntax, which enables you to match on the beginning of + a binary.)</p> + <p><marker id="smp_support"></marker>In the runtime system with + SMP support, drivers are locked either on driver level + or port level (driver instance level). By default + driver level locking will be used, that is, only one emulator thread will execute code in the driver at a time. If port level locking - is used, multiple emulator threads may execute code in the driver - at the same time. There will only be one thread at a time calling - driver call-backs corresponding to the same port, though. In order - to enable port level locking set the <c>ERL_DRV_FLAG_USE_PORT_LOCKING</c> + is used, multiple emulator threads can execute code in the driver + at the same time. Only one thread at a time will call + driver callbacks corresponding to the same port, though. + To enable port level locking, set the <c>ERL_DRV_FLAG_USE_PORT_LOCKING</c> <seealso marker="driver_entry#driver_flags">driver flag</seealso> in - the <seealso marker="driver_entry">driver_entry</seealso> - used by the driver. When port level locking is used it is the - responsibility of the driver writer to synchronize all accesses + the <seealso marker="driver_entry"><c>driver_entry</c></seealso> + used by the driver. When port level locking is used, + the driver writer is responsible for synchronizing all accesses to data shared by the ports (driver instances).</p> + <p>Most drivers written before the runtime system with SMP - support existed will be able to run in the runtime system - with SMP support without being rewritten if driver + support existed can run in the runtime system + with SMP support, without being rewritten, if driver level locking is used.</p> + <note> <p>It is assumed that drivers do not access other drivers. If - drivers should access each other they have to provide their own - mechanism for thread safe synchronization. Such "inter driver + drivers access each other, they must provide their own + mechanism for thread-safe synchronization. Such "inter-driver communication" is strongly discouraged.</p> </note> + <p>Previously, in the runtime system without SMP support, - specific driver call-backs were always called from the same + specific driver callbacks were always called from the same thread. This is <em>not</em> the case in the runtime system with SMP support. Regardless of locking scheme used, calls - to driver call-backs may be made from different threads, e.g., - two consecutive calls to exactly the same call-back for exactly - the same port may be made from two different threads. This - will for <em>most</em> drivers not be a problem, but it might. - Drivers that depend on all call-backs being called in the - same thread, <em>have</em> to be rewritten before being used + to driver callbacks can be made from different threads. For example, + two consecutive calls to exactly the same callback for exactly + the same port can be made from two different threads. This + is for <em>most</em> drivers not a problem, but it can be. + Drivers that depend on all callbacks that are called in the + same thread, <em>must</em> be rewritten before they are used in the runtime system with SMP support.</p> + <note> <p>Regardless of locking scheme used, calls to driver - call-backs may be made from different threads.</p> + callbacks can be made from different threads.</p> </note> - <p>Most functions in this API are <em>not</em> thread-safe, i.e., - they may <em>not</em> be called from an arbitrary thread. Functions - that are not documented as thread-safe may only be called from - driver call-backs or function calls descending from a driver - call-back call. Note that driver call-backs may be called from + + <p>Most functions in this API are <em>not</em> thread-safe, that is, + they <em>cannot</em> be called from any thread. Functions + that are not documented as thread-safe can only be called from + driver callbacks or function calls descending from a driver + callback call. Notice that driver callbacks can be called from different threads. This, however, is not a problem for any - function in this API, since the emulator has control over + function in this API, as the emulator has control over these threads.</p> + <warning> - <p>Functions not explicitly documented as thread safe are - <em>not</em> thread safe. Also note that some functions - are <em>only</em> thread safe when used in a runtime + <p>Functions not explicitly documented as thread-safe are + <em>not</em> thread safe. Also notice that some functions + are <em>only</em> thread-safe when used in a runtime system with SMP support.</p> - <p>A function not explicitly documented as thread safe may at - some point in time have a thread safe implementation in the - runtime system. Such an implementation may however change to - a thread <em>unsafe</em> implementation at any time <em>without - any notice</em> at all. - </p> - <p><em>Only use functions explicitly documented as thread safe - from arbitrary threads.</em></p> + <p>A function not explicitly documented as thread-safe can, at + some point in time, have a thread-safe implementation in the + runtime system. Such an implementation can however change to + a thread <em>unsafe</em> implementation at any time <em>without + any notice</em>.</p> + <p><em>Only use functions explicitly documented as thread-safe + from arbitrary threads.</em></p> </warning> - <p><marker id="lengthy_work"/> - As mentioned in the <seealso marker="#WARNING">warning</seealso> text at - the beginning of this document it is of vital importance that a driver callback - does return relatively fast. It is hard to give an exact maximum amount - of time that a driver callback is allowed to work, but as a rule of thumb - a well behaving driver callback should return before a millisecond has - passed. This can be achieved using different approaches. - If you have full control over the code that are to execute in the driver - callback, the best approach is to divide the work into multiple chunks of - work and trigger multiple calls to the - <seealso marker="driver_entry#timeout">timeout callback</seealso> using - zero timeouts. The - <seealso marker="#erl_drv_consume_timeslice"><c>erl_drv_consume_timeslice()</c></seealso> - function can be useful in order to determine when to trigger such - timeout callback calls. It might, however, not always be possible to - implement it this way, e.g. when calling third party libraries. In this - case you typically want to dispatch the work to another thread. - Information about thread primitives can be found below.</p> + + <p><marker id="lengthy_work"/> + As mentioned in the <seealso marker="#WARNING">warning</seealso> text at + the beginning of this section, it is of vital importance that a driver + callback returns relatively fast. It is difficult to give an exact + maximum amount of time that a driver callback is allowed to work, but + usually a well-behaving driver callback is to return within 1 millisecond. + This can be achieved using different approaches. + If you have full control over the code to execute in the driver + callback, the best approach is to divide the work into multiple chunks of + work, and trigger multiple calls to the + <seealso marker="driver_entry#timeout">time-out callback</seealso> using + zero time-outs. Function <seealso marker="#erl_drv_consume_timeslice"> + <c>erl_drv_consume_timeslice</c></seealso> can be useful to + determine when to trigger such time-out callback calls. However, sometimes + it cannot be implemented this way, for example when calling + third-party libraries. In this case, you typically want to dispatch the + work to another thread. Information about thread primitives is provided + below.</p> </description> <section> - <title>FUNCTIONALITY</title> + <title>Functionality</title> <p>All functions that a driver needs to do with Erlang are - performed through driver API functions. There are functions + performed through driver API functions. Functions exist for the following functionality:</p> + <taglist> <tag>Timer functions</tag> - <item>Timer functions are used to control the timer that a driver - may use. The timer will have the emulator call the - <seealso marker="driver_entry#timeout">timeout</seealso> entry - function after a specified time. Only one timer is available - for each driver instance.</item> + <item> + <p>Control the timer that a driver can use. The timer has the + emulator call the <seealso marker="driver_entry#timeout"> + <c>timeout</c></seealso> entry function after a specified time. + Only one timer is available for each driver instance.</p> + </item> <tag>Queue handling</tag> <item> <p>Every driver instance has an associated queue. This queue is a - <c>SysIOVec</c> that works as a buffer. It's mostly used for - the driver to buffer data that should be written to a device, + <c>SysIOVec</c>, which works as a buffer. It is mostly used for + the driver to buffer data that is to be written to a device, it is a byte stream. If the port owner process closes the - driver, and the queue is not empty, the driver will not be + driver, and the queue is not empty, the driver is not closed. This enables the driver to flush its buffers before closing.</p> - <p>The queue can be manipulated from arbitrary threads if - a port data lock is used. See documentation of the - <seealso marker="#ErlDrvPDL">ErlDrvPDL</seealso> type for - more information.</p> + <p>The queue can be manipulated from any threads if + a port data lock is used. For more information, see + <seealso marker="#ErlDrvPDL"><c>ErlDrvPDL</c></seealso>.</p> </item> <tag>Output functions</tag> - <item>With the output functions, the driver sends data back to - the emulator. They will be received as messages by the port owner - process, see <c>open_port/2</c>. The vector function and the - function taking a driver binary are faster, because they avoid - copying the data buffer. There is also a fast way of sending - terms from the driver, without going through the binary term - format.</item> + <item> + <p>With these functions, the driver sends data back to the emulator. + The data is received as messages by the port owner process, see + <seealso marker="erlang:open_port/2"> + <c>erlang:open_port/2</c></seealso>. The vector function and the + function taking a driver binary are faster, as they avoid + copying the data buffer. There is also a fast way of sending + terms from the driver, without going through the binary term + format.</p></item> <tag>Failure</tag> - <item>The driver can exit and signal errors up to Erlang. This is - only for severe errors, when the driver can't possibly keep - open.</item> + <item> + <p>The driver can exit and signal errors up to Erlang. This is + only for severe errors, when the driver cannot possibly keep + open.</p> + </item> <tag>Asynchronous calls</tag> - <item>The latest Erlang versions (R7B and later) has provision for - asynchronous function calls, using a thread pool provided by - Erlang. There is also a select call, that can be used for - asynchronous drivers.</item> + <item> + <p>Erlang/OTP R7B and later versions have provision for + asynchronous function calls, using a thread pool provided by + Erlang. There is also a select call, which can be used for + asynchronous drivers.</p> + </item> <tag><marker id="multi_threading"/>Multi-threading</tag> <item> - <p>A POSIX thread like API for multi-threading is provided. The - Erlang driver thread API only provide a subset of the functionality - provided by the POSIX thread API. The subset provided is - more or less the basic functionality needed for multi-threaded - programming: - </p> - <list> - <item><seealso marker="#ErlDrvTid">Threads</seealso></item> - <item><seealso marker="#ErlDrvMutex">Mutexes</seealso></item> - <item><seealso marker="#ErlDrvCond">Condition variables</seealso></item> - <item><seealso marker="#ErlDrvRWLock">Read/Write locks</seealso></item> - <item><seealso marker="#ErlDrvTSDKey">Thread specific data</seealso></item> - </list> - <p>The Erlang driver thread API can be used in conjunction with - the POSIX thread API on UN-ices and with the Windows native thread - API on Windows. The Erlang driver thread API has the advantage of - being portable, but there might exist situations where you want to - use functionality from the POSIX thread API or the Windows - native thread API. - </p> - <p>The Erlang driver thread API only returns error codes when it is - reasonable to recover from an error condition. If it isn't reasonable - to recover from an error condition, the whole runtime system is - terminated. For example, if a create mutex operation fails, an error - code is returned, but if a lock operation on a mutex fails, the - whole runtime system is terminated. - </p> - <p>Note that there exists no "condition variable wait with timeout" in - the Erlang driver thread API. This is due to issues with - <c>pthread_cond_timedwait()</c>. When the system clock suddenly - is changed, it isn't always guaranteed that you will wake up from - the call as expected. An Erlang runtime system has to be able to - cope with sudden changes of the system clock. Therefore, we have - omitted it from the Erlang driver thread API. In the Erlang driver - case, timeouts can and should be handled with the timer functionality - of the Erlang driver API. - </p> - <p>In order for the Erlang driver thread API to function, thread - support has to be enabled in the runtime system. An Erlang driver - can check if thread support is enabled by use of - <seealso marker="#driver_system_info">driver_system_info()</seealso>. - Note that some functions in the Erlang driver API are thread-safe - only when the runtime system has SMP support, also this - information can be retrieved via - <seealso marker="#driver_system_info">driver_system_info()</seealso>. - Also note that a lot of functions in the Erlang driver API are - <em>not</em> thread-safe regardless of whether SMP support is - enabled or not. If a function isn't documented as thread-safe it - is <em>not</em> thread-safe. - </p> - <p><em>NOTE</em>: When executing in an emulator thread, it is - <em>very important</em> that you unlock <em>all</em> locks you - have locked before letting the thread out of your control; - otherwise, you are <em>very likely</em> to deadlock the whole - emulator. If you need to use thread specific data in an emulator - thread, only have the thread specific data set while the thread is - under your control, and clear the thread specific data before - you let the thread out of your control. - </p> - <p>In the future there will probably be debug functionality - integrated with the Erlang driver thread API. All functions - that create entities take a <c>name</c> argument. Currently - the <c>name</c> argument is unused, but it will be used when - the debug functionality has been implemented. If you name all - entities created well, the debug functionality will be able - to give you better error reports. - </p> + <p>A POSIX thread like API for multi-threading is provided. The + Erlang driver thread API only provides a subset of the functionality + provided by the POSIX thread API. The subset provided is + more or less the basic functionality needed for multi-threaded + programming:</p> + <list> + <item><seealso marker="#ErlDrvTid">Threads</seealso></item> + <item><seealso marker="#ErlDrvMutex">Mutexes</seealso></item> + <item><seealso marker="#ErlDrvCond"> + Condition variables</seealso></item> + <item><seealso marker="#ErlDrvRWLock"> + Read/write locks</seealso></item> + <item><seealso marker="#ErlDrvTSDKey"> + Thread-specific data</seealso></item> + </list> + <p>The Erlang driver thread API can be used in conjunction with + the POSIX thread API on UN-ices and with the Windows native thread + API on Windows. The Erlang driver thread API has the advantage of + being portable, but there can exist situations where you want to + use functionality from the POSIX thread API or the Windows + native thread API.</p> + <p>The Erlang driver thread API only returns error codes when it is + reasonable to recover from an error condition. If it is not reasonable + to recover from an error condition, the whole runtime system is + terminated. For example, if a create mutex operation fails, an error + code is returned, but if a lock operation on a mutex fails, the + whole runtime system is terminated.</p> + <p>Notice that there is no "condition variable wait with time-out" in + the Erlang driver thread API. This because of issues with + <c>pthread_cond_timedwait</c>. When the system clock suddenly + is changed, it is not always guaranteed that you will wake up from + the call as expected. An Erlang runtime system must be able to + cope with sudden changes of the system clock. Therefore, we have + omitted it from the Erlang driver thread API. In the Erlang driver + case, time-outs can and are to be handled with the timer functionality + of the Erlang driver API.</p> + <p>In order for the Erlang driver thread API to function, thread + support must be enabled in the runtime system. An Erlang driver + can check if thread support is enabled by use of + <seealso marker="#driver_system_info"> + <c>driver_system_info</c></seealso>. + Notice that some functions in the Erlang driver API are thread-safe + only when the runtime system has SMP support, also this + information can be retrieved through + <seealso marker="#driver_system_info"> + <c>driver_system_info</c></seealso>. + Also notice that many functions in the Erlang driver API are + <em>not</em> thread-safe, regardless of whether SMP support is + enabled or not. If a function is not documented as thread-safe, it + is <em>not</em> thread-safe.</p> + <note> + <p>When executing in an emulator thread, it is + <em>very important</em> that you unlock <em>all</em> locks you + have locked before letting the thread out of your control; + otherwise you are <em>very likely</em> to deadlock the whole + emulator.</p> + <p>If you need to use thread-specific data in an emulator + thread, only have the thread-specific data set while the thread is + under your control, and clear the thread-specific data before + you let the thread out of your control.</p> + </note> + <p>In the future, debug functionality will probably be + integrated with the Erlang driver thread API. All functions + that create entities take a <c>name</c> argument. Currently + the <c>name</c> argument is unused, but it will be used when + the debug functionality is implemented. If you name all + entities created well, the debug functionality will be able + to give you better error reports.</p> + </item> + <tag>Adding/removing drivers</tag> + <item> + <p>A driver can add and later remove drivers.</p> </item> - <tag>Adding / removing drivers</tag> - <item><p>A driver can add and later remove drivers.</p></item> <tag>Monitoring processes</tag> - <item><p>A driver can monitor a process that does not own a port.</p></item> + <item> + <p>A driver can monitor a process that does not own a port.</p> + </item> <tag><marker id="version_management"/>Version management</tag> <item> <p>Version management is enabled for drivers that have set the - <seealso marker="driver_entry#extended_marker">extended_marker</seealso> - field of their - <seealso marker="driver_entry">driver_entry</seealso> - to <c>ERL_DRV_EXTENDED_MARKER</c>. <c>erl_driver.h</c> defines - <c>ERL_DRV_EXTENDED_MARKER</c>, - <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c>, and - <c>ERL_DRV_EXTENDED_MINOR_VERSION</c>. - <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c> will be incremented when - driver incompatible changes are made to the Erlang runtime - system. Normally it will suffice to recompile drivers when the - <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c> has changed, but it - could, under rare circumstances, mean that drivers have to - be slightly modified. If so, this will of course be documented. - <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> will be incremented when - new features are added. The runtime system uses the minor version - of the driver to determine what features to use. - The runtime system will normally refuse to load a driver if the major + <seealso marker="driver_entry#extended_marker"> + <c>extended_marker</c></seealso> field of their + <seealso marker="driver_entry"><c>driver_entry</c></seealso> + to <c>ERL_DRV_EXTENDED_MARKER</c>. <c>erl_driver.h</c> defines:</p> + <list type="bulleted"> + <item> + <p><c>ERL_DRV_EXTENDED_MARKER</c></p> + </item> + <item> + <p><c>ERL_DRV_EXTENDED_MAJOR_VERSION</c>, which is incremented when + driver incompatible changes are made to the Erlang runtime + system. Normally it suffices to recompile drivers when + <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c> has changed, but it + can, under rare circumstances, mean that drivers must + be slightly modified. If so, this will of course be + documented.</p> + </item> + <item> + <p><c>ERL_DRV_EXTENDED_MINOR_VERSION</c>, which is incremented when + new features are added. The runtime system uses the minor version + of the driver to determine what features to use.</p> + </item> + </list> + <p>The runtime system normally refuses to load a driver if the major versions differ, or if the major versions are equal and the minor version used by the driver is greater than the one used by the runtime system. Old drivers with lower major versions - will however be allowed after a bump of the major version during - a transition period of two major releases. Such old drivers might - however fail if deprecated features are used.</p> - <p>The emulator will refuse to load a driver that does not use - the extended driver interface, - to allow for 64-bit capable drivers, - since incompatible type changes for the callbacks - <seealso marker="driver_entry#output">output</seealso>, - <seealso marker="driver_entry#control">control</seealso> and - <seealso marker="driver_entry#call">call</seealso> - were introduced in release R15B. A driver written - with the old types would compile with warnings and when - called return garbage sizes to the emulator causing it - to read random memory and create huge incorrect result blobs.</p> - <p>Therefore it is not enough to just recompile drivers written with - version management for pre-R15B types; the types have to be changed - in the driver suggesting other rewrites especially regarding - size variables. Investigate all warnings when recompiling!</p> - <p>Also, the API driver functions <c>driver_output*</c>, - <c>driver_vec_to_buf</c>, <c>driver_alloc/realloc*</c> - and the <c>driver_*</c> queue functions were changed to have - larger length arguments and return values. This is a - lesser problem since code that passes smaller types - will get them auto converted in the calls and as long as - the driver does not handle sizes that overflow an <c>int</c> - all will work as before.</p> + are however allowed after a bump of the major version during + a transition period of two major releases. Such old drivers can, + however, fail if deprecated features are used.</p> + <p>The emulator refuses to load a driver that does not use + the extended driver interface, to allow for 64-bit capable drivers, + as incompatible type changes for the callbacks + <seealso marker="driver_entry#output"><c>output</c></seealso>, + <seealso marker="driver_entry#control"><c>control</c></seealso>, and + <seealso marker="driver_entry#call"><c>call</c></seealso> + were introduced in Erlang/OTP R15B. A driver written + with the old types would compile with warnings and when + called return garbage sizes to the emulator, causing it + to read random memory and create huge incorrect result blobs.</p> + <p>Therefore it is not enough to only recompile drivers written with + version management for pre R15B types; the types must be changed + in the driver suggesting other rewrites, especially regarding size + variables. <em>Investigate all warnings when recompiling.</em></p> + <p>Also, the API driver functions <c>driver_output*</c> and + <c>driver_vec_to_buf</c>, <c>driver_alloc/realloc*</c>, and the + <c>driver_*</c> queue functions were changed to have + larger length arguments and return values. This is a + lesser problem, as code that passes smaller types + gets them auto-converted in the calls, and as long as + the driver does not handle sizes that overflow an <c>int</c>, + all will work as before.</p> </item> - <tag><marker id="time_measurement"/>Time Measurement</tag> - <item><p>Support for time measurement in drivers: - <list> - <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> - <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> - <item><seealso marker="#erl_drv_monotonic_time"><c>erl_drv_monotonic_time()</c></seealso></item> - <item><seealso marker="#erl_drv_time_offset"><c>erl_drv_time_offset()</c></seealso></item> - <item><seealso marker="#erl_drv_convert_time_unit"><c>erl_drv_convert_time_unit()</c></seealso></item> - </list></p> + <tag><marker id="time_measurement"/>Time measurement</tag> + <item> + <p>Support for time measurement in drivers:</p> + <list type="bulleted"> + <item><seealso marker="#ErlDrvTime"> + <c>ErlDrvTime</c></seealso></item> + <item><seealso marker="#ErlDrvTimeUnit"> + <c>ErlDrvTimeUnit</c></seealso></item> + <item><seealso marker="#erl_drv_monotonic_time"> + <c>erl_drv_monotonic_time</c></seealso></item> + <item><seealso marker="#erl_drv_time_offset"> + <c>erl_drv_time_offset</c></seealso></item> + <item><seealso marker="#erl_drv_convert_time_unit"> + <c>erl_drv_convert_time_unit</c></seealso></item> + </list> </item> </taglist> </section> <section> <marker id="rewrites_for_64_bits"/> - <title> - REWRITES FOR 64-BIT DRIVER INTERFACE - </title> - <p> - For erts-5.9 two new integer types - <seealso marker="#ErlDrvSizeT">ErlDrvSizeT</seealso> and - <seealso marker="#ErlDrvSSizeT">ErlDrvSSizeT</seealso> - were introduced that can hold 64-bit sizes if necessary. - </p> - <p> - To not update a driver and just recompile it probably works + <title>Rewrites for 64-Bit Driver Interface</title> + <p>ERTS 5.9 introduced two new integer types, + <seealso marker="#ErlDrvSizeT"><c>ErlDrvSizeT</c></seealso> and + <seealso marker="#ErlDrvSSizeT"><c>ErlDrvSSizeT</c></seealso>, + which can hold 64-bit sizes if necessary.</p> + + <p>To not update a driver and only recompile, it probably works when building for a 32-bit machine creating a false sense of security. Hopefully that will generate many important warnings. - But when recompiling the same driver later on for a 64-bit machine + But when recompiling the same driver later on for a 64-bit machine, there <em>will</em> be warnings and almost certainly crashes. - So it is a BAD idea to postpone updating the driver and - not fixing the warnings! - </p> - <p> - When recompiling with <c>gcc</c> use the <c>-Wstrict-prototypes</c> - flag to get better warnings. Try to find a similar flag if you - are using some other compiler. - </p> - <p> - Here follows a checklist for rewriting a pre erts-5.9 driver, - most important first. - </p> + So it is a <em>bad</em> idea to postpone updating the driver and + not fixing the warnings.</p> + + <p>When recompiling with <c>gcc</c>, use flag <c>-Wstrict-prototypes</c> + to get better warnings. Try to find a similar flag if you use + another compiler.</p> + + <p>The following is a checklist for rewriting a pre ERTS 5.9 driver, + most important first:</p> + <taglist> <tag>Return types for driver callbacks</tag> <item> - <p> - Rewrite driver callback + <p>Rrewrite driver callback <seealso marker="driver_entry#control"><c>control</c></seealso> - to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>. - </p> - <p> - Rewrite driver callback + to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>.</p> + <p>Rewrite driver callback <seealso marker="driver_entry#call"><c>call</c></seealso> - to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>. - </p> + to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>.</p> <note> - <p> - These changes are essential to not crash the emulator + <p>These changes are essential not to crash the emulator or worse cause malfunction. - Without them a driver may return garbage in the high 32 bits - to the emulator causing it to build a huge result from random - bytes either crashing on memory allocation or succeeding with - a random result from the driver call. - </p> + Without them a driver can return garbage in the high 32 bits + to the emulator, causing it to build a huge result from random + bytes, either crashing on memory allocation or succeeding with + a random result from the driver call.</p> </note> </item> <tag>Arguments to driver callbacks</tag> <item> - <p> - Driver callback + <p>Driver callback <seealso marker="driver_entry#output"><c>output</c></seealso> now gets <c>ErlDrvSizeT</c> as 3rd argument instead - of previously <c>int</c>. - </p> - <p> - Driver callback + of previously <c>int</c>.</p> + <p>Driver callback <seealso marker="driver_entry#control"><c>control</c></seealso> now gets <c>ErlDrvSizeT</c> as 4th and 6th arguments instead - of previously <c>int</c>. - </p> - <p> - Driver callback + of previously <c>int</c>.</p> + <p>Driver callback <seealso marker="driver_entry#call"><c>call</c></seealso> now gets <c>ErlDrvSizeT</c> as 4th and 6th arguments instead - of previously <c>int</c>. - </p> - <p> - Sane compiler's calling conventions probably make these changes + of previously <c>int</c>.</p> + <p>Sane compiler's calling conventions probably make these changes necessary only for a driver to handle data chunks that require - 64-bit size fields (mostly larger than 2 GB since that is what + 64-bit size fields (mostly larger than 2 GB, as that is what an <c>int</c> of 32 bits can hold). But it is possible to think of non-sane calling conventions that would make the driver - callbacks mix up the arguments causing malfunction. - </p> + callbacks mix up the arguments causing malfunction.</p> <note> - <p> - The argument type change is from signed to unsigned which - may cause problems for e.g. loop termination conditions or - error conditions if you just change the types all over the place. - </p> + <p>The argument type change is from signed to unsigned. This + can cause problems for, for example, loop termination conditions or + error conditions if you only change the types all over the place. + </p> </note> </item> <tag>Larger <c>size</c> field in <c>ErlIOVec</c></tag> <item> - <p> - The <c>size</c> field in + <p>The <c>size</c> field in <seealso marker="#ErlIOVec"><c>ErlIOVec</c></seealso> has been changed to <c>ErlDrvSizeT</c> from <c>int</c>. - Check all code that use that field. - </p> - <p> - Automatic type casting probably makes these changes necessary only - for a driver that encounters sizes larger than 32 bits. - </p> + Check all code that use that field.</p> + <p>Automatic type-casting probably makes these changes necessary only + for a driver that encounters sizes > 32 bits.</p> <note> - <p> - The <c>size</c> field changed from signed to unsigned which - may cause problems for e.g. loop termination conditions or - error conditions if you just change the types all over the place. - </p> + <p>The <c>size</c> field changed from signed to unsigned. This + can cause problems for, for example, loop termination conditions or + error conditions if you only change the types all over the place. + </p> </note> </item> <tag>Arguments and return values in the driver API</tag> <item> - <p> - Many driver API functions have changed argument type + <p>Many driver API functions have changed argument type and/or return value to <c>ErlDrvSizeT</c> from mostly <c>int</c>. - Automatic type casting probably makes these changes necessary only - for a driver that encounters sizes larger than 32 bits. - </p> + Automatic type-casting probably makes these changes necessary only + for a driver that encounters sizes > 32 bits.</p> <taglist> - <tag><seealso marker="#driver_output">driver_output</seealso></tag> + <tag><seealso marker="#driver_output"> + <c>driver_output</c></seealso></tag> <item>3rd argument</item> - <tag><seealso marker="#driver_output2">driver_output2</seealso></tag> + <tag><seealso marker="#driver_output2"> + <c>driver_output2</c></seealso></tag> <item>3rd and 5th arguments</item> - <tag> - <seealso marker="#driver_output_binary">driver_output_binary</seealso> - </tag> - <item>3rd 5th and 6th arguments</item> - <tag><seealso marker="#driver_outputv">driver_outputv</seealso></tag> + <tag><seealso marker="#driver_output_binary"> + <c>driver_output_binary</c></seealso></tag> + <item>3rd, 5th, and 6th arguments</item> + <tag><seealso marker="#driver_outputv"> + <c>driver_outputv</c></seealso></tag> <item>3rd and 5th arguments</item> - <tag> - <seealso marker="#driver_vec_to_buf">driver_vec_to_buf</seealso> - </tag> + <tag><seealso marker="#driver_vec_to_buf"> + <c>driver_vec_to_buf</c></seealso></tag> <item>3rd argument and return value</item> - <tag><seealso marker="#driver_alloc">driver_alloc</seealso></tag> + <tag><seealso marker="#driver_alloc"> + <c>driver_alloc</c></seealso></tag> <item>1st argument</item> - <tag><seealso marker="#driver_realloc">driver_realloc</seealso></tag> + <tag><seealso marker="#driver_realloc"> + <c>driver_realloc</c></seealso></tag> <item>2nd argument</item> - <tag> - <seealso marker="#driver_alloc_binary">driver_alloc_binary</seealso> - </tag> + <tag><seealso marker="#driver_alloc_binary"> + <c>driver_alloc_binary</c></seealso></tag> <item>1st argument</item> - <tag> - <seealso marker="#driver_realloc_binary">driver_realloc_binary</seealso> - </tag> + <tag><seealso marker="#driver_realloc_binary"> + <c>driver_realloc_binary</c></seealso></tag> <item>2nd argument</item> - <tag><seealso marker="#driver_enq">driver_enq</seealso></tag> + <tag><seealso marker="#driver_enq"> + <c>driver_enq</c></seealso></tag> <item>3rd argument</item> - <tag><seealso marker="#driver_pushq">driver_pushq</seealso></tag> + <tag><seealso marker="#driver_pushq"> + <c>driver_pushq</c></seealso></tag> <item>3rd argument</item> - <tag><seealso marker="#driver_deq">driver_deq</seealso></tag> + <tag><seealso marker="#driver_deq"> + <c>driver_deq</c></seealso></tag> <item>2nd argument and return value</item> - <tag><seealso marker="#driver_sizeq">driver_sizeq</seealso></tag> - <item>return value</item> - <tag><seealso marker="#driver_enq_bin">driver_enq_bin</seealso></tag> - <item>3rd and 4th argument</item> - <tag><seealso marker="#driver_pushq_bin">driver_pushq_bin</seealso></tag> - <item>3rd and 4th argument</item> - <tag><seealso marker="#driver_enqv">driver_enqv</seealso></tag> + <tag><seealso marker="#driver_sizeq"> + <c>driver_sizeq</c></seealso></tag> + <item>Return value</item> + <tag><seealso marker="#driver_enq_bin"> + <c>driver_enq_bin</c></seealso></tag> + <item>3rd and 4th arguments</item> + <tag><seealso marker="#driver_pushq_bin"> + <c>driver_pushq_bin</c></seealso></tag> + <item>3rd and 4th arguments</item> + <tag><seealso marker="#driver_enqv"> + <c>driver_enqv</c></seealso></tag> <item>3rd argument</item> - <tag><seealso marker="#driver_pushqv">driver_pushqv</seealso></tag> + <tag><seealso marker="#driver_pushqv"> + <c>driver_pushqv</c></seealso></tag> <item>3rd argument</item> - <tag><seealso marker="#driver_peekqv">driver_peekqv</seealso></tag> - <item>return value</item> + <tag><seealso marker="#driver_peekqv"> + <c>driver_peekqv</c></seealso></tag> + <item>Return value</item> </taglist> <note> - <p> - This is a change from signed to unsigned which - may cause problems for e.g. loop termination conditions and - error conditions if you just change the types all over the place. - </p> + <p>This is a change from signed to unsigned. This can cause + problems for, for example, loop termination conditions and error + conditions if you only change the types all over the place.</p> </note> </item> </taglist> </section> <section> - <title>DATA TYPES</title> - + <title>Data Types</title> <taglist> - <tag><marker id="ErlDrvSizeT"/>ErlDrvSizeT</tag> - <item><p>An unsigned integer type to be used as <c>size_t</c></p></item> - <tag><marker id="ErlDrvSSizeT"/>ErlDrvSSizeT</tag> - <item><p>A signed integer type the size of <c>ErlDrvSizeT</c></p></item> - <tag><marker id="ErlDrvSysInfo"/>ErlDrvSysInfo</tag> + <tag><marker id="ErlDrvSizeT"/><c>ErlDrvSizeT</c></tag> + <item> + <p>An unsigned integer type to be used as <c>size_t</c>.</p> + </item> + <tag><marker id="ErlDrvSSizeT"/><c>ErlDrvSSizeT</c></tag> <item> - <p/> - <code type="none"> + <p>A signed integer type, the size of <c>ErlDrvSizeT</c>.</p> + </item> + <tag><marker id="ErlDrvSysInfo"/><c>ErlDrvSysInfo</c></tag> + <item> + <code type="none"> typedef struct ErlDrvSysInfo { int driver_major_version; int driver_minor_version; @@ -558,2565 +583,2633 @@ typedef struct ErlDrvSysInfo { int nif_major_version; int nif_minor_version; int dirty_scheduler_support; -} ErlDrvSysInfo; - </code> - - <p> - The <c>ErlDrvSysInfo</c> structure is used for storage of - information about the Erlang runtime system. - <seealso marker="#driver_system_info">driver_system_info()</seealso> - will write the system information when passed a reference to - a <c>ErlDrvSysInfo</c> structure. A description of the - fields in the structure follows: - </p> - <taglist> - <tag><c>driver_major_version</c></tag> - <item>The value of - <seealso marker="#version_management">ERL_DRV_EXTENDED_MAJOR_VERSION</seealso> - when the runtime system was compiled. This value is the same - as the value of - <seealso marker="#version_management">ERL_DRV_EXTENDED_MAJOR_VERSION</seealso> - used when compiling the driver; otherwise, the runtime system - would have refused to load the driver. - </item> - <tag><c>driver_minor_version</c></tag> - <item>The value of - <seealso marker="#version_management">ERL_DRV_EXTENDED_MINOR_VERSION</seealso> - when the runtime system was compiled. This value might differ - from the value of - <seealso marker="#version_management">ERL_DRV_EXTENDED_MINOR_VERSION</seealso> - used when compiling the driver. - </item> - <tag><c>erts_version</c></tag> - <item>A string containing the version number of the runtime system - (the same as returned by - <seealso marker="erlang#system_info_version">erlang:system_info(version)</seealso>). - </item> - <tag><c>otp_release</c></tag> - <item>A string containing the OTP release number - (the same as returned by - <seealso marker="erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>). - </item> - <tag><c>thread_support</c></tag> - <item>A value <c>!= 0</c> if the runtime system has thread support; - otherwise, <c>0</c>. - </item> - <tag><c>smp_support</c></tag> - <item>A value <c>!= 0</c> if the runtime system has SMP support; - otherwise, <c>0</c>. - </item> - <tag><c>async_threads</c></tag> - <item>The number of async threads in the async thread pool used - by <seealso marker="#driver_async">driver_async()</seealso> - (the same as returned by - <seealso marker="erlang#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</seealso>). - </item> - <tag><c>scheduler_threads</c></tag> - <item>The number of scheduler threads used by the runtime system - (the same as returned by - <seealso marker="erlang#system_info_schedulers">erlang:system_info(schedulers)</seealso>). - </item> - <tag><c>nif_major_version</c></tag> - <item>The value of <c>ERL_NIF_MAJOR_VERSION</c> when the runtime system was compiled. - </item> - <tag><c>nif_minor_version</c></tag> - <item>The value of <c>ERL_NIF_MINOR_VERSION</c> when the runtime system was compiled. - </item> - <tag><c>dirty_scheduler_support</c></tag> - <item>A value <c>!= 0</c> if the runtime system has support for dirty scheduler threads; - otherwise <c>0</c>. - </item> +} ErlDrvSysInfo;</code> + <p>The <c>ErlDrvSysInfo</c> structure is used for storage of + information about the Erlang runtime system. + <seealso marker="#driver_system_info"> + <c>driver_system_info</c></seealso> + writes the system information when passed a reference to + a <c>ErlDrvSysInfo</c> structure. The fields in the structure + are as follows:</p> + <taglist> + <tag><c>driver_major_version</c></tag> + <item> + <p>The value of <seealso marker="#version_management"> + <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c></seealso> + when the runtime system was compiled. This value is the same + as the value of <seealso marker="#version_management"> + <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c></seealso> + used when compiling the driver; otherwise the runtime system + would have refused to load the driver.</p> + </item> + <tag><c>driver_minor_version</c></tag> + <item> + <p>The value of <seealso marker="#version_management"> + <c>ERL_DRV_EXTENDED_MINOR_VERSION</c></seealso> + when the runtime system was compiled. This value can differ + from the value of <seealso marker="#version_management"> + <c>ERL_DRV_EXTENDED_MINOR_VERSION</c></seealso> + used when compiling the driver.</p> + </item> + <tag><c>erts_version</c></tag> + <item> + <p>A string containing the version number of the runtime system + (the same as returned by + <seealso marker="erlang#system_info_version"> + <c>erlang:system_info(version)</c></seealso>).</p> + </item> + <tag><c>otp_release</c></tag> + <item> + <p>A string containing the OTP release number + (the same as returned by + <seealso marker="erlang#system_info_otp_release"> + <c>erlang:system_info(otp_release)</c></seealso>).</p> + </item> + <tag><c>thread_support</c></tag> + <item> + <p>A value <c>!= 0</c> if the runtime system has thread support; + otherwise <c>0</c>.</p> + </item> + <tag><c>smp_support</c></tag> + <item> + <p>A value <c>!= 0</c> if the runtime system has SMP support; + otherwise <c>0</c>.</p> + </item> + <tag><c>async_threads</c></tag> + <item> + <p>The number of async threads in the async thread pool used by + <seealso marker="#driver_async"><c>driver_async</c></seealso> + (the same as returned by + <seealso marker="erlang#system_info_thread_pool_size"> + <c>erlang:system_info(thread_pool_size)</c></seealso>).</p> + </item> + <tag><c>scheduler_threads</c></tag> + <item> + <p>The number of scheduler threads used by the runtime system + (the same as returned by + <seealso marker="erlang#system_info_schedulers"> + <c>erlang:system_info(schedulers)</c></seealso>).</p> + </item> + <tag><c>nif_major_version</c></tag> + <item> + <p>The value of <c>ERL_NIF_MAJOR_VERSION</c> when the runtime + system was compiled.</p> + </item> + <tag><c>nif_minor_version</c></tag> + <item> + <p>The value of <c>ERL_NIF_MINOR_VERSION</c> when the runtime + system was compiled.</p> + </item> + <tag><c>dirty_scheduler_support</c></tag> + <item> + <p>A value <c>!= 0</c> if the runtime system has support for dirty + scheduler threads; otherwise <c>0</c>.</p> + </item> </taglist> </item> - <tag><marker id="ErlDrvBinary"/>ErlDrvBinary</tag> + <tag><marker id="ErlDrvBinary"/><c>ErlDrvBinary</c></tag> <item> - <p/> - <code type="none"> + <code type="none"> typedef struct ErlDrvBinary { ErlDrvSint orig_size; char orig_bytes[]; -} ErlDrvBinary; -</code> +} ErlDrvBinary;</code> <p>The <c>ErlDrvBinary</c> structure is a binary, as sent between the emulator and the driver. All binaries are reference counted; when <c>driver_binary_free</c> is called, the reference count is decremented, when it reaches zero, - the binary is deallocated. The <c>orig_size</c> is the size - of the binary, and <c>orig_bytes</c> is the buffer. The - <c>ErlDrvBinary</c> does not have a fixed size, its size is + the binary is deallocated. <c>orig_size</c> is the binary size + and <c>orig_bytes</c> is the buffer. + <c>ErlDrvBinary</c> has not a fixed size, its size is <c>orig_size + 2 * sizeof(int)</c>.</p> <note> <p>The <c>refc</c> field has been removed. The reference count of an <c>ErlDrvBinary</c> is now stored elsewhere. The - reference count of an <c>ErlDrvBinary</c> can be accessed via - <seealso marker="#driver_binary_get_refc">driver_binary_get_refc()</seealso>, - <seealso marker="#driver_binary_inc_refc">driver_binary_inc_refc()</seealso>, - and - <seealso marker="#driver_binary_dec_refc">driver_binary_dec_refc()</seealso>.</p> + reference count of an <c>ErlDrvBinary</c> can be accessed through + <seealso marker="#driver_binary_get_refc"> + <c>driver_binary_get_refc</c></seealso>, + <seealso marker="#driver_binary_inc_refc"> + <c>driver_binary_inc_refc</c></seealso>, and + <seealso marker="#driver_binary_dec_refc"> + <c>driver_binary_dec_refc</c></seealso>.</p> </note> <p>Some driver calls, such as <c>driver_enq_binary</c>, increment the driver reference count, and others, such as <c>driver_deq</c> decrement it.</p> - <p>Using a driver binary instead of a normal buffer, is often - faster, since the emulator doesn't need to copy the data, + <p>Using a driver binary instead of a normal buffer is often + faster, as the emulator needs not to copy the data, only the pointer is used.</p> <p>A driver binary allocated in the driver, with - <c>driver_alloc_binary</c>, should be freed in the driver (unless otherwise stated), - with <c>driver_free_binary</c>. (Note that this doesn't + <c>driver_alloc_binary</c>, is to be freed in the driver + (unless otherwise stated) + with <c>driver_free_binary</c>. (Notice that this does not necessarily deallocate it, if the driver is still referred in the emulator, the ref-count will not go to zero.)</p> <p>Driver binaries are used in the <c>driver_output2</c> and <c>driver_outputv</c> calls, and in the queue. Also the - driver call-back <seealso marker="driver_entry#outputv">outputv</seealso> uses driver - binaries.</p> - <p>If the driver for some reason or another, wants to keep a - driver binary around, in a static variable for instance, the - reference count should be incremented, - and the binary can later be freed in the <seealso marker="driver_entry#stop">stop</seealso> call-back, with - <c>driver_free_binary</c>.</p> - <p>Note that since a driver binary is shared by the driver and - the emulator, a binary received from the emulator or sent to - the emulator, must not be changed by the driver.</p> - <p>Since erts version 5.5 (OTP release R11B), orig_bytes is + driver callback <seealso marker="driver_entry#outputv"> + <c>outputv</c></seealso> uses driver binaries.</p> + <p>If the driver for some reason wants to keep a + driver binary around, for example in a static variable, the + reference count is to be incremented, and the binary can later + be freed in the <seealso marker="driver_entry#stop"> + <c>stop</c></seealso> callback, with <c>driver_free_binary</c>.</p> + <p>Notice that as a driver binary is shared by the driver and + the emulator. A binary received from the emulator or sent to + the emulator must not be changed by the driver.</p> + <p>Since ERTS 5.5 (Erlang/OTP R11B), <c>orig_bytes</c> is guaranteed to be properly aligned for storage of an array of doubles (usually 8-byte aligned).</p> </item> - <tag>ErlDrvData</tag> + <tag><c>ErlDrvData</c></tag> <item> - <p>The <c>ErlDrvData</c> is a handle to driver-specific data, - passed to the driver call-backs. It is a pointer, and is + <p>A handle to driver-specific data, + passed to the driver callbacks. It is a pointer, and is most often type cast to a specific pointer in the driver.</p> </item> - <tag>SysIOVec</tag> + <tag><c>SysIOVec</c></tag> <item> - <p>This is a system I/O vector, as used by <c>writev</c> on - unix and <c>WSASend</c> on Win32. It is used in + <p>A system I/O vector, as used by <c>writev</c> on + Unix and <c>WSASend</c> on Win32. It is used in <c>ErlIOVec</c>.</p> </item> - <tag><marker id="ErlIOVec"/>ErlIOVec</tag> + <tag><marker id="ErlIOVec"/><c>ErlIOVec</c></tag> <item> - <p/> - <code type="none"> + <code type="none"> typedef struct ErlIOVec { int vsize; ErlDrvSizeT size; SysIOVec* iov; ErlDrvBinary** binv; -} ErlIOVec; -</code> - <p>The I/O vector used by the emulator and drivers, is a list +} ErlIOVec;</code> + <p>The I/O vector used by the emulator and drivers is a list of binaries, with a <c>SysIOVec</c> pointing to the buffers of the binaries. It is used in <c>driver_outputv</c> and the - <seealso marker="driver_entry#outputv">outputv</seealso> - driver call-back. Also, the driver queue is an + <seealso marker="driver_entry#outputv"><c>outputv</c></seealso> + driver callback. Also, the driver queue is an <c>ErlIOVec</c>.</p> </item> - - <tag>ErlDrvMonitor</tag> + <tag><c>ErlDrvMonitor</c></tag> <item> <p>When a driver creates a monitor for a process, a <c>ErlDrvMonitor</c> is filled in. This is an opaque - data-type which can be assigned to but not compared without - using the supplied compare function (i.e. it behaves like a struct).</p> - <p>The driver writer should provide the memory for storing the - monitor when calling <seealso marker="#driver_monitor_process">driver_monitor_process</seealso>. The + data type that can be assigned to, but not compared without + using the supplied compare function (that is, it behaves like + a struct).</p> + <p>The driver writer is to provide the memory for storing the + monitor when calling <seealso marker="#driver_monitor_process"> + <c>driver_monitor_process</c></seealso>. The address of the data is not stored outside of the driver, so - the <c>ErlDrvMonitor</c> can be used as any other datum, it - can be copied, moved in memory, forgotten etc.</p> + <c>ErlDrvMonitor</c> can be used as any other data, it + can be copied, moved in memory, forgotten, and so on.</p> </item> - <tag><marker id="ErlDrvNowData"/>ErlDrvNowData</tag> + <tag><marker id="ErlDrvNowData"/><c>ErlDrvNowData</c></tag> <item> - <p>The <c>ErlDrvNowData</c> structure holds a timestamp + <p>The <c>ErlDrvNowData</c> structure holds a time stamp consisting of three values measured from some arbitrary point in the past. The three structure members are:</p> <taglist> - <tag>megasecs</tag> + <tag><c>megasecs</c></tag> <item>The number of whole megaseconds elapsed since the arbitrary - point in time</item> - <tag>secs</tag> + point in time</item> + <tag><c>secs</c></tag> <item>The number of whole seconds elapsed since the arbitrary - point in time</item> - <tag>microsecs</tag> + point in time</item> + <tag><c>microsecs</c></tag> <item>The number of whole microseconds elapsed since the arbitrary - point in time</item> + point in time</item> </taglist> </item> - <tag><marker id="ErlDrvPDL"/>ErlDrvPDL</tag> + <tag><marker id="ErlDrvPDL"/><c>ErlDrvPDL</c></tag> <item> - <p>If certain port specific data have to be accessed from other - threads than those calling the driver call-backs, a port data lock - can be used in order to synchronize the operations on the data. - Currently, the only port specific data that the emulator + <p>If certain port-specific data must be accessed from other + threads than those calling the driver callbacks, a port data lock + can be used to synchronize the operations on the data. + Currently, the only port-specific data that the emulator associates with the port data lock is the driver queue.</p> - <p>Normally a driver instance does not have a port data lock. If - the driver instance wants to use a port data lock, it has to + <p>Normally a driver instance has no port data lock. If + the driver instance wants to use a port data lock, it must create the port data lock by calling - <seealso marker="#driver_pdl_create">driver_pdl_create()</seealso>. - <em>NOTE</em>: Once the port data lock has been created, every - access to data associated with the port data lock has to be done - while having the port data lock locked. The port data lock is - locked, and unlocked, respectively, by use of - <seealso marker="#driver_pdl_lock">driver_pdl_lock()</seealso>, and - <seealso marker="#driver_pdl_unlock">driver_pdl_unlock()</seealso>.</p> + <seealso marker="#driver_pdl_create"> + <c>driver_pdl_create</c></seealso>.</p> + <note> + <p>Once the port data lock has been created, every + access to data associated with the port data lock must be done + while the port data lock is locked. The port data lock is + locked and unlocked by + <seealso marker="#driver_pdl_lock"> + <c>driver_pdl_lock</c></seealso>, and + <seealso marker="#driver_pdl_unlock"> + <c>driver_pdl_unlock</c></seealso>, respectively.</p> + </note> <p>A port data lock is reference counted, and when the reference - count reaches zero, it will be destroyed. The emulator will at - least increment the reference count once when the lock is - created and decrement it once when the port associated with - the lock terminates. The emulator will also increment the - reference count when an async job is enqueued and decrement - it after an async job has been invoked. Besides - this, it is the responsibility of the driver to ensure that + count reaches zero, it is destroyed. The emulator at + least increments the reference count once when the lock is + created and decrements it once the port associated with + the lock terminates. The emulator also increments the + reference count when an async job is enqueued and decrements + it when an async job has been invoked. + Also, the driver is responsible for ensuring that the reference count does not reach zero before the last use of the lock by the driver has been made. The reference count - can be read, incremented, and decremented, respectively, by - use of - <seealso marker="#driver_pdl_get_refc">driver_pdl_get_refc()</seealso>, - <seealso marker="#driver_pdl_inc_refc">driver_pdl_inc_refc()</seealso>, and - <seealso marker="#driver_pdl_dec_refc">driver_pdl_dec_refc()</seealso>.</p> + can be read, incremented, and decremented by + <seealso marker="#driver_pdl_get_refc"> + <c>driver_pdl_get_refc</c></seealso>, + <seealso marker="#driver_pdl_inc_refc"> + <c>driver_pdl_inc_refc</c></seealso>, and + <seealso marker="#driver_pdl_dec_refc"> + <c>driver_pdl_dec_refc</c></seealso>, respectively.</p> </item> - - <tag><marker id="ErlDrvTid"/>ErlDrvTid</tag> + <tag><marker id="ErlDrvTid"/><c>ErlDrvTid</c></tag> <item> <p>Thread identifier.</p> - <p>See also: - <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>, - <seealso marker="#erl_drv_thread_exit">erl_drv_thread_exit()</seealso>, - <seealso marker="#erl_drv_thread_join">erl_drv_thread_join()</seealso>, - <seealso marker="#erl_drv_thread_self">erl_drv_thread_self()</seealso>, - and - <seealso marker="#erl_drv_equal_tids">erl_drv_equal_tids()</seealso>. - </p> + <p>See also <seealso marker="#erl_drv_thread_create"> + <c>erl_drv_thread_create</c></seealso>, + <seealso marker="#erl_drv_thread_exit"> + <c>erl_drv_thread_exit</c></seealso>, + <seealso marker="#erl_drv_thread_join"> + <c>erl_drv_thread_join</c></seealso>, + <seealso marker="#erl_drv_thread_self"> + <c>erl_drv_thread_self</c></seealso>, and + <seealso marker="#erl_drv_equal_tids"> + <c>erl_drv_equal_tids</c></seealso>.</p> </item> - <tag><marker id="ErlDrvThreadOpts"/>ErlDrvThreadOpts</tag> + <tag><marker id="ErlDrvThreadOpts"/><c>ErlDrvThreadOpts</c></tag> <item> - <p/> - <code type="none"> - int suggested_stack_size; - </code> + <code type="none"> +int suggested_stack_size;</code> <p>Thread options structure passed to - <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>. - Currently the following fields exist: - </p> + <seealso marker="#erl_drv_thread_create"> + <c>erl_drv_thread_create</c></seealso>. + The following fields exists:</p> <taglist> - <tag>suggested_stack_size</tag> - <item>A suggestion, in kilo-words, on how large a stack to use. A value less - than zero means default size. + <tag><c>suggested_stack_size</c></tag> + <item>A suggestion, in kilowords, on how large a stack to use. + A value < 0 means default size. </item> </taglist> - <p>See also: - <seealso marker="#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</seealso>, - <seealso marker="#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy()</seealso>, - and - <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>. - </p> + <p>See also <seealso marker="#erl_drv_thread_opts_create"> + <c>erl_drv_thread_opts_create</c></seealso>, + <seealso marker="#erl_drv_thread_opts_destroy"> + <c>erl_drv_thread_opts_destroy</c></seealso>, and + <seealso marker="#erl_drv_thread_create"> + <c>erl_drv_thread_create</c></seealso>.</p> </item> - - <tag><marker id="ErlDrvMutex"/>ErlDrvMutex</tag> + <tag><marker id="ErlDrvMutex"/><c>ErlDrvMutex</c></tag> <item> <p>Mutual exclusion lock. Used for synchronizing access to shared data. - Only one thread at a time can lock a mutex. - </p> - <p>See also: - <seealso marker="#erl_drv_mutex_create">erl_drv_mutex_create()</seealso>, - <seealso marker="#erl_drv_mutex_destroy">erl_drv_mutex_destroy()</seealso>, - <seealso marker="#erl_drv_mutex_lock">erl_drv_mutex_lock()</seealso>, - <seealso marker="#erl_drv_mutex_trylock">erl_drv_mutex_trylock()</seealso>, - and - <seealso marker="#erl_drv_mutex_unlock">erl_drv_mutex_unlock()</seealso>. - </p> + Only one thread at a time can lock a mutex.</p> + <p>See also <seealso marker="#erl_drv_mutex_create"> + <c>erl_drv_mutex_create</c></seealso>, + <seealso marker="#erl_drv_mutex_destroy"> + <c>erl_drv_mutex_destroy</c></seealso>, + <seealso marker="#erl_drv_mutex_lock"> + <c>erl_drv_mutex_lock</c></seealso>, + <seealso marker="#erl_drv_mutex_trylock"> + <c>erl_drv_mutex_trylock</c></seealso>, and + <seealso marker="#erl_drv_mutex_unlock"> + <c>erl_drv_mutex_unlock</c></seealso>.</p> </item> - <tag><marker id="ErlDrvCond"/>ErlDrvCond</tag> + <tag><marker id="ErlDrvCond"/><c>ErlDrvCond</c></tag> <item> - <p>Condition variable. Used when threads need to wait for a specific - condition to appear before continuing execution. Condition variables - need to be used with associated mutexes. - </p> - <p>See also: - <seealso marker="#erl_drv_cond_create">erl_drv_cond_create()</seealso>, - <seealso marker="#erl_drv_cond_destroy">erl_drv_cond_destroy()</seealso>, - <seealso marker="#erl_drv_cond_signal">erl_drv_cond_signal()</seealso>, - <seealso marker="#erl_drv_cond_broadcast">erl_drv_cond_broadcast()</seealso>, - and - <seealso marker="#erl_drv_cond_wait">erl_drv_cond_wait()</seealso>. - </p> + <p>Condition variable. Used when threads must wait for a specific + condition to appear before continuing execution. Condition variables + must be used with associated mutexes.</p> + <p>See also <seealso marker="#erl_drv_cond_create"> + <c>erl_drv_cond_create</c></seealso>, + <seealso marker="#erl_drv_cond_destroy"> + <c>erl_drv_cond_destroy</c></seealso>, + <seealso marker="#erl_drv_cond_signal"> + <c>erl_drv_cond_signal</c></seealso>, + <seealso marker="#erl_drv_cond_broadcast"> + <c>erl_drv_cond_broadcast</c></seealso>, and + <seealso marker="#erl_drv_cond_wait"> + <c>erl_drv_cond_wait</c></seealso>.</p> </item> - <tag><marker id="ErlDrvRWLock"/>ErlDrvRWLock</tag> + <tag><marker id="ErlDrvRWLock"/><c>ErlDrvRWLock</c></tag> <item> <p>Read/write lock. Used to allow multiple threads to read shared data - while only allowing one thread to write the same data. Multiple threads - can read lock an rwlock at the same time, while only one thread can - read/write lock an rwlock at a time. - </p> - <p>See also: - <seealso marker="#erl_drv_rwlock_create">erl_drv_rwlock_create()</seealso>, - <seealso marker="#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy()</seealso>, - <seealso marker="#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock()</seealso>, - <seealso marker="#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock()</seealso>, - <seealso marker="#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock()</seealso>, - <seealso marker="#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock()</seealso>, - <seealso marker="#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock()</seealso>, - and - <seealso marker="#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock()</seealso>. - </p> + while only allowing one thread to write the same data. Multiple + threads can read lock an rwlock at the same time, while only + one thread can read/write lock an rwlock at a time.</p> + <p>See also <seealso marker="#erl_drv_rwlock_create"> + <c>erl_drv_rwlock_create</c></seealso>, + <seealso marker="#erl_drv_rwlock_destroy"> + <c>erl_drv_rwlock_destroy</c></seealso>, + <seealso marker="#erl_drv_rwlock_rlock"> + <c>erl_drv_rwlock_rlock</c></seealso>, + <seealso marker="#erl_drv_rwlock_tryrlock"> + <c>erl_drv_rwlock_tryrlock</c></seealso>, + <seealso marker="#erl_drv_rwlock_runlock"> + <c>erl_drv_rwlock_runlock</c></seealso>, + <seealso marker="#erl_drv_rwlock_rwlock"> + <c>erl_drv_rwlock_rwlock</c></seealso>, + <seealso marker="#erl_drv_rwlock_tryrwlock"> + <c>erl_drv_rwlock_tryrwlock</c></seealso>, and + <seealso marker="#erl_drv_rwlock_rwunlock"> + <c>erl_drv_rwlock_rwunlock</c></seealso>.</p> </item> - <tag><marker id="ErlDrvTSDKey"/>ErlDrvTSDKey</tag> + <tag><marker id="ErlDrvTSDKey"/><c>ErlDrvTSDKey</c></tag> <item> - <p>Key which thread specific data can be associated with.</p> - <p>See also: - <seealso marker="#erl_drv_tsd_key_create">erl_drv_tsd_key_create()</seealso>, - <seealso marker="#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy()</seealso>, - <seealso marker="#erl_drv_tsd_set">erl_drv_tsd_set()</seealso>, - and - <seealso marker="#erl_drv_tsd_get">erl_drv_tsd_get()</seealso>. - </p> + <p>Key that thread-specific data can be associated with.</p> + <p>See also <seealso marker="#erl_drv_tsd_key_create"> + <c>erl_drv_tsd_key_create</c></seealso>, + <seealso marker="#erl_drv_tsd_key_destroy"> + <c>erl_drv_tsd_key_destroy</c></seealso>, + <seealso marker="#erl_drv_tsd_set"> + <c>erl_drv_tsd_set</c></seealso>, and + <seealso marker="#erl_drv_tsd_get"> + <c>erl_drv_tsd_get</c></seealso>.</p> </item> - <tag><marker id="ErlDrvTime"/>ErlDrvTime</tag> + <tag><marker id="ErlDrvTime"/><c>ErlDrvTime</c></tag> <item> - <p>A signed 64-bit integer type for representation of time.</p> + <p>A signed 64-bit integer type for time representation.</p> </item> - <tag><marker id="ErlDrvTimeUnit"/>ErlDrvTimeUnit</tag> + <tag><marker id="ErlDrvTimeUnit"/><c>ErlDrvTimeUnit</c></tag> <item> <p>An enumeration of time units supported by the driver API:</p> - <taglist> + <taglist> <tag><c>ERL_DRV_SEC</c></tag> - <item><p>Seconds</p></item> + <item>Seconds</item> <tag><c>ERL_DRV_MSEC</c></tag> - <item><p>Milliseconds</p></item> + <item>Milliseconds</item> <tag><c>ERL_DRV_USEC</c></tag> - <item><p>Microseconds</p></item> + <item>Microseconds</item> <tag><c>ERL_DRV_NSEC</c></tag> - <item><p>Nanoseconds</p></item> - </taglist> + <item>Nanoseconds</item> + </taglist> </item> - </taglist> - </section> + </taglist> + </section> <funcs> <func> - <name><ret>void</ret><nametext>driver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size)</nametext></name> - <fsummary>Get information about the Erlang runtime system</fsummary> + <name><ret>void</ret><nametext>add_driver_entry(ErlDrvEntry + *de)</nametext></name> + <fsummary>Add a driver entry.</fsummary> <desc> - <marker id="driver_system_info"></marker> - <p>This function will write information about the Erlang runtime - system into the - <seealso marker="#ErlDrvSysInfo">ErlDrvSysInfo</seealso> - structure referred to by the first argument. The second - argument should be the size of the - <seealso marker="#ErlDrvSysInfo">ErlDrvSysInfo</seealso> - structure, i.e., <c>sizeof(ErlDrvSysInfo)</c>.</p> - <p>See the documentation of the - <seealso marker="#ErlDrvSysInfo">ErlDrvSysInfo</seealso> - structure for information about specific fields.</p> + <marker id="add_driver_entry"></marker> + <p>Adds a driver entry to the list of drivers known by Erlang. + The <seealso marker="driver_entry#init"><c>init</c></seealso> + function of parameter <c>de</c> is called.</p> + <note> + <p>To use this function for adding drivers residing in + dynamically loaded code is dangerous. If the driver code + for the added driver resides in the same dynamically + loaded module (that is, <c>.so</c> file) as a normal + dynamically loaded driver (loaded with the <c>erl_ddll</c> + interface), the caller is to call + <seealso marker="#driver_lock_driver"> + <c>driver_lock_driver</c></seealso> before + adding driver entries.</p> + <p><em>Use of this function is generally deprecated.</em></p> + </note> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len)</nametext></name> - <fsummary>Send data from driver to port owner</fsummary> + <name><ret>void *</ret> + <nametext>driver_alloc(ErlDrvSizeT size)</nametext></name> + <fsummary>Allocate memory.</fsummary> <desc> - <marker id="driver_output"></marker> - <p>The <c>driver_output</c> function is used to send data from - the driver up to the emulator. The data will be received as - terms or binary data, depending on how the driver port was - opened.</p> - <p>The data is queued in the port owner process' message - queue. Note that this does not yield to the emulator. (Since - the driver and the emulator run in the same thread.)</p> - <p>The parameter <c>buf</c> points to the data to send, and - <c>len</c> is the number of bytes.</p> - <p>The return value for all output functions is 0. (Unless the - driver is used for distribution, in which case it can fail - and return -1. For normal use, the output function always - returns 0.)</p> + <marker id="driver_alloc"></marker> + <p>Allocates a memory block of the size specified + in <c>size</c>, and returns it. This fails only on out of + memory, in which case <c>NULL</c> is returned. (This is most + often a wrapper for <c>malloc</c>).</p> + <p>Memory allocated must be explicitly freed with a corresponding + call to <seealso marker="#driver_free"><c>driver_free</c></seealso> + (unless otherwise stated).</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)</nametext></name> - <fsummary>Send data and binary data to port owner</fsummary> + <name><ret>ErlDrvBinary *</ret> + <nametext>driver_alloc_binary(ErlDrvSizeT size)</nametext></name> + <fsummary>Allocate a driver binary.</fsummary> <desc> - <marker id="driver_output2"></marker> - <p>The <c>driver_output2</c> function first sends <c>hbuf</c> - (length in <c>hlen</c>) data as a list, regardless of port - settings. Then <c>buf</c> is sent as a binary or list. - E.g. if <c>hlen</c> is 3 then the port owner process will - receive <c>[H1, H2, H3 | T]</c>.</p> - <p>The point of sending data as a list header, is to facilitate - matching on the data received.</p> - <p>The return value is 0 for normal use.</p> + <marker id="driver_alloc_binary"></marker> + <p>Allocates a driver binary with a memory block + of at least <c>size</c> bytes, and returns a pointer to it, + or <c>NULL</c> on failure (out of memory). When a driver binary has + been sent to the emulator, it must not be changed. Every + allocated binary is to be freed by a corresponding call to + <seealso marker="#driver_free_binary"> + <c>driver_free_binary</c></seealso> (unless otherwise stated).</p> + <p>Notice that a driver binary has an internal reference counter. + This means that calling <c>driver_free_binary</c>, it may not + actually dispose of it. If it is sent to the emulator, it can + be referenced there.</p> + <p>The driver binary has a field, <c>orig_bytes</c>, which + marks the start of the data in the binary.</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name> - <fsummary>Send data from a driver binary to port owner</fsummary> + <name><ret>long</ret><nametext>driver_async(ErlDrvPort port, unsigned + int* key, void (*async_invoke)(void*), void* async_data, void + (*async_free)(void*))</nametext></name> + <fsummary>Perform an asynchronous call within a driver.</fsummary> <desc> - <marker id="driver_output_binary"></marker> - <p>This function sends data to port owner process from a - driver binary, it has a header buffer (<c>hbuf</c> - and <c>hlen</c>) just like <c>driver_output2</c>. The - <c>hbuf</c> parameter can be <c>NULL</c>.</p> - <p>The parameter <c>offset</c> is an offset into the binary and - <c>len</c> is the number of bytes to send.</p> - <p>Driver binaries are created with <c>driver_alloc_binary</c>.</p> - <p>The data in the header is sent as a list and the binary as - an Erlang binary in the tail of the list.</p> - <p>E.g. if <c>hlen</c> is 2, then the port owner process will - receive <c><![CDATA[[H1, H2 | <<T>>]]]></c>.</p> - <p>The return value is 0 for normal use.</p> - <p>Note that, using the binary syntax in Erlang, the driver - application can match the header directly from the binary, - so the header can be put in the binary, and hlen can be set - to 0.</p> + <marker id="driver_async"></marker> + <p>Performs an asynchronous call. The function + <c>async_invoke</c> is invoked in a thread separate from the + emulator thread. This enables the driver to perform + time-consuming, blocking operations without blocking the + emulator.</p> + <p>The async thread pool size can be set with command-line argument + <seealso marker="erl#async_thread_pool_size"><c>+A</c></seealso> + in <seealso marker="erl"><c>erl(1)</c></seealso>. + If an async thread pool is unavailable, the call is made + synchronously in the thread calling <c>driver_async</c>. The + current number of async threads in the async thread pool can be + retrieved through <seealso marker="#driver_system_info"> + <c>driver_system_info</c></seealso>.</p> + <p>If a thread pool is available, a thread is used. + If argument <c>key</c> is <c>NULL</c>, the threads from the + pool are used in a round-robin way, each call to + <c>driver_async</c> uses the next thread in the pool. With + argument <c>key</c> set, this behavior is changed. The two + same values of <c>*key</c> always get the same thread.</p> + <p>To ensure that a driver instance always uses the same + thread, the following call can be used:</p> + <code type="none"><![CDATA[ +unsigned int myKey = driver_async_port_key(myPort); + +r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> + <p>It is enough to initialize <c>myKey</c> once for each + driver instance.</p> + <p>If a thread is already working, the calls are + queued up and executed in order. Using the same thread for + each driver instance ensures that the calls are made in sequence.</p> + <p>The <c>async_data</c> is the argument to the functions + <c>async_invoke</c> and <c>async_free</c>. It is typically a + pointer to a structure containing a pipe or event that + can be used to signal that the async operation completed. + The data is to be freed in <c>async_free</c>.</p> + <p>When the async operation is done, + <seealso marker="driver_entry#ready_async"> + <c>ready_async</c></seealso> driver + entry function is called. If <c>ready_async</c> is <c>NULL</c> in + the driver entry, the <c>async_free</c> function is called + instead.</p> + <p>The return value is <c>-1</c> if the <c>driver_async</c> call + fails.</p> + <note> + <p>As from ERTS 5.5.4.3 the default stack size for + threads in the async-thread pool is 16 kilowords, + that is, 64 kilobyte on 32-bit architectures. + This small default size has been chosen because the + amount of async-threads can be quite large. The + default stack size is enough for drivers delivered + with Erlang/OTP, but is possibly not sufficiently large + for other dynamically linked-in drivers that use the + <c>driver_async</c> functionality. A suggested stack size + for threads in the async-thread pool can be configured + through command-line argument + <seealso marker="erl#async_thread_stack_size"><c>+a</c></seealso> + in <seealso marker="erl"><c>erl(1)</c></seealso>.</p> + </note> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name> - <fsummary>Send vectorized data to port owner</fsummary> + <name><ret>unsigned int</ret><nametext>driver_async_port_key(ErlDrvPort + port)</nametext></name> + <fsummary>Calculate an async key from an ErlDrvPort.</fsummary> <desc> - <marker id="driver_outputv"></marker> - <p>This function sends data from an IO vector, <c>ev</c>, to - the port owner process. It has a header buffer (<c>hbuf</c> - and <c>hlen</c>), just like <c>driver_output2</c>.</p> - <p>The <c>skip</c> parameter is a number of bytes to skip of - the <c>ev</c> vector from the head.</p> - <p>You get vectors of <c>ErlIOVec</c> type from the driver - queue (see below), and the <seealso marker="driver_entry#outputv">outputv</seealso> driver entry - function. You can also make them yourself, if you want to - send several <c>ErlDrvBinary</c> buffers at once. Often - it is faster to use <c>driver_output</c> or - <c>driver_output_binary</c>.</p> - <p>E.g. if <c>hlen</c> is 2 and <c>ev</c> points to an array of - three binaries, the port owner process will receive <c><![CDATA[[H1, H2, <<B1>>, <<B2>> | <<B3>>]]]></c>.</p> - <p>The return value is 0 for normal use.</p> - <p>The comment for <c>driver_output_binary</c> applies for - <c>driver_outputv</c> too.</p> + <marker id="driver_async_port_key"></marker> + <p>Calculates a key for later use in <seealso + marker="#driver_async"><c>driver_async</c></seealso>. The keys are + evenly distributed so that a fair mapping between port IDs + and async thread IDs is achieved.</p> + <note> + <p>Before Erlang/OTP R16, the port ID could be used as a key + with proper casting, but after the rewrite of the port + subsystem, this is no longer the case. With this function, you + can achieve the same distribution based on port IDs as before + Erlang/OTP R16.</p> + </note> </desc> </func> + <func> - <name><ret>ErlDrvSizeT</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len)</nametext></name> - <fsummary>Collect data segments into a buffer</fsummary> + <name><ret>long</ret> + <nametext>driver_binary_dec_refc(ErlDrvBinary *bin)</nametext></name> + <fsummary>Decrement the reference count of a driver binary.</fsummary> <desc> - <marker id="driver_vec_to_buf"></marker> - <p>This function collects several segments of data, referenced - by <c>ev</c>, by copying them in order to the buffer - <c>buf</c>, of the size <c>len</c>.</p> - <p>If the data is to be sent from the driver to the port owner - process, it is faster to use <c>driver_outputv</c>.</p> - <p>The return value is the space left in the buffer, i.e. if - the <c>ev</c> contains less than <c>len</c> bytes it's the - difference, and if <c>ev</c> contains <c>len</c> bytes or - more, it's 0. This is faster if there is more than one header byte, - since the binary syntax can construct integers directly from - the binary.</p> + <marker id="driver_binary_dec_refc"></marker> + <p>Decrements the reference count on <c>bin</c> and returns + the reference count reached after the decrement.</p> + <p>This function is thread-safe.</p> + <note> + <p>The reference count of driver binary is normally to be decremented + by calling <seealso marker="#driver_free_binary"> + <c>driver_free_binary</c></seealso>.</p> + <p><c>driver_binary_dec_refc</c> does <em>not</em> free + the binary if the reference count reaches zero. <em>Only</em> + use <c>driver_binary_dec_refc</c> when you are sure + <em>not</em> to reach a reference count of zero.</p> + </note> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_set_timer(ErlDrvPort port, unsigned long time)</nametext></name> - <fsummary>Set a timer to call the driver</fsummary> + <name><ret>long</ret> + <nametext>driver_binary_get_refc(ErlDrvBinary *bin)</nametext></name> + <fsummary>Get the reference count of a driver binary.</fsummary> <desc> - <marker id="driver_set_timer"></marker> - <p>This function sets a timer on the driver, which will count - down and call the driver when it is timed out. The - <c>time</c> parameter is the time in milliseconds before the - timer expires.</p> - <p>When the timer reaches 0 and expires, the driver entry - function <seealso marker="driver_entry#timeout">timeout</seealso> is called.</p> - <p>Note that there is only one timer on each driver instance; - setting a new timer will replace an older one.</p> - <p>Return value is 0 (-1 only when the <c>timeout</c> driver - function is <c>NULL</c>).</p> + <marker id="driver_binary_get_refc"></marker> + <p>Returns the current reference count on <c>bin</c>.</p> + <p>This function is thread-safe.</p> + </desc> + </func> + + <func> + <name><ret>long</ret> + <nametext>driver_binary_inc_refc(ErlDrvBinary *bin)</nametext></name> + <fsummary>Increment the reference count of a driver binary.</fsummary> + <desc> + <marker id="driver_binary_inc_refc"></marker> + <p>Increments the reference count on <c>bin</c> and returns + the reference count reached after the increment.</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_cancel_timer(ErlDrvPort port)</nametext></name> - <fsummary>Cancel a previously set timer</fsummary> + <name><ret>ErlDrvTermData</ret><nametext>driver_caller(ErlDrvPort + port)</nametext></name> + <fsummary>Return the process making the driver call.</fsummary> + <desc> + <marker id="driver_caller"></marker> + <p>Returns the process ID of the process that + made the current call to the driver. The process ID can be used with + <seealso marker="#driver_send_term"><c>driver_send_term</c></seealso> + to send back data to the caller. + <c>driver_caller</c> only returns valid data + when currently executing in one of the following driver callbacks:</p> + <taglist> + <tag><seealso marker="driver_entry#start"> + <c>start</c></seealso></tag> + <item>Called from <seealso marker="erlang:open_port/2"> + <c>erlang:open_port/2</c></seealso>.</item> + <tag><seealso marker="driver_entry#output"> + <c>output</c></seealso></tag> + <item>Called from <seealso marker="erlang:send/2"> + <c>erlang:send/2</c></seealso> and + <seealso marker="erlang:port_command/2"> + <c>erlang:port_command/2</c></seealso>.</item> + <tag><seealso marker="driver_entry#outputv"> + <c>outputv</c></seealso></tag> + <item>Called from <seealso marker="erlang:send/2"> + <c>erlang:send/2</c></seealso> and + <seealso marker="erlang:port_command/2"> + <c>erlang:port_command/2</c></seealso>.</item> + <tag><seealso marker="driver_entry#control"> + <c>control</c></seealso></tag> + <item>Called from <seealso marker="erlang:port_control/3"> + <c>erlang:port_control/3</c></seealso>.</item> + <tag><seealso marker="driver_entry#call"> + <c>call</c></seealso></tag> + <item>Called from <seealso marker="erlang:port_call/3"> + <c>erlang:port_call/3</c></seealso>.</item> + </taglist> + <p>Notice that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> + </desc> + </func> + + <func> + <name><ret>int</ret> + <nametext>driver_cancel_timer(ErlDrvPort port)</nametext></name> + <fsummary>Cancel a previously set timer.</fsummary> <desc> <marker id="driver_cancel_timer"></marker> - <p>This function cancels a timer set with - <c>driver_set_timer</c>.</p> - <p>The return value is 0.</p> + <p>Cancels a timer set with + <seealso marker="#driver_set_timer"> + <c>driver_set_timer</c></seealso>.</p> + <p>The return value is <c>0</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_read_timer(ErlDrvPort port, unsigned long *time_left)</nametext></name> - <fsummary>Read the time left before timeout</fsummary> + <name><ret>int</ret><nametext>driver_compare_monitors(const ErlDrvMonitor + *monitor1, const ErlDrvMonitor *monitor2)</nametext></name> + <fsummary>Compare two monitors.</fsummary> <desc> - <marker id="driver_read_timer"></marker> - <p>This function reads the current time of a timer, and places - the result in <c>time_left</c>. This is the time in - milliseconds, before the timeout will occur.</p> - <p>The return value is 0.</p> + <marker id="driver_compare_monitors"></marker> + <p>Compares two <c>ErlDrvMonitor</c>s. + Can also be used to imply some artificial order on monitors, + for whatever reason.</p> + <p>Returns <c>0</c> if <c>monitor1</c> and <c>monitor2</c> are equal, + < <c>0</c> if <c>monitor1</c> < <c>monitor2</c>, and + > <c>0</c> if <c>monitor1</c> > <c>monitor2</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_get_now(ErlDrvNowData *now)</nametext></name> - <fsummary>Read a system timestamp</fsummary> + <name><ret>ErlDrvTermData</ret><nametext>driver_connected(ErlDrvPort + port)</nametext></name> + <fsummary>Return the port owner process.</fsummary> <desc> - <marker id="driver_get_now"></marker> - <warning><p><em>This function is deprecated! Do not use it!</em> - Use <seealso marker="#erl_drv_monotonic_time"><c>erl_drv_monotonic_time()</c></seealso> - (perhaps in combination with - <seealso marker="#erl_drv_time_offset"><c>erl_drv_time_offset()</c></seealso>) - instead.</p></warning> - <p>This function reads a timestamp into the memory pointed to by - the parameter <c>now</c>. See the description of <seealso marker="#ErlDrvNowData">ErlDrvNowData</seealso> for - specification of its fields. </p> - <p>The return value is 0 unless the <c>now</c> pointer is not - valid, in which case it is < 0. </p> + <marker id="driver_connected"></marker> + <p>Returns the port owner process.</p> + <p>Notice that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on)</nametext></name> - <fsummary>Provide an event for having the emulator call the driver</fsummary> + <name><ret>ErlDrvPort</ret><nametext>driver_create_port(ErlDrvPort port, + ErlDrvTermData owner_pid, char* name, + ErlDrvData drv_data)</nametext></name> + <fsummary>Create a new port (driver instance).</fsummary> <desc> - <marker id="driver_select"></marker> - <p>This function is used by drivers to provide the emulator with - events to check for. This enables the emulator to call the driver - when something has happened asynchronously.</p> - <p>The <c>event</c> argument identifies an OS-specific event object. - On Unix systems, the functions <c>select</c>/<c>poll</c> are used. The - event object must be a socket or pipe (or other object that - <c>select</c>/<c>poll</c> can use). - On windows, the Win32 API function <c>WaitForMultipleObjects</c> - is used. This places other restrictions on the event object. - Refer to the Win32 SDK documentation. - On Enea OSE, the receive function is used. See the <seealso - marker="ose:ose_erl_driver"></seealso> for more details.</p> - <p>The <c>on</c> parameter should be <c>1</c> for setting events - and <c>0</c> for clearing them.</p> - <p>The <c>mode</c> argument is a bitwise-or combination of - <c>ERL_DRV_READ</c>, <c>ERL_DRV_WRITE</c> and <c>ERL_DRV_USE</c>. - The first two specify whether to wait for read events and/or write - events. A fired read event will call - <seealso marker="driver_entry#ready_input">ready_input</seealso> - while a fired write event will call - <seealso marker="driver_entry#ready_output">ready_output</seealso>. - </p> - <note> - <p>Some OS (Windows and Enea OSE) do not differentiate between read and write events. - The call-back for a fired event then only depends on the value of <c>mode</c>.</p> - </note> - <p><c>ERL_DRV_USE</c> specifies if we are using the event object or if we want to close it. - On an emulator with SMP support, it is not safe to clear all events - and then close the event object after <c>driver_select</c> has - returned. Another thread may still be using the event object - internally. To safely close an event object call - <c>driver_select</c> with <c>ERL_DRV_USE</c> and <c>on==0</c>. That - will clear all events and then call - <seealso marker="driver_entry#stop_select">stop_select</seealso> - when it is safe to close the event object. - <c>ERL_DRV_USE</c> should be set together with the first event - for an event object. It is harmless to set <c>ERL_DRV_USE</c> - even though it already has been done. Clearing all events but keeping - <c>ERL_DRV_USE</c> set will indicate that we are using the event - object and probably will set events for it again.</p> - <note> - <p>ERL_DRV_USE was added in OTP release R13. Old drivers will still work - as before. But it is recommended to update them to use <c>ERL_DRV_USE</c> and - <c>stop_select</c> to make sure that event objects are closed in a safe way.</p> - </note> - <p>The return value is 0 (failure, -1, only if the - <c>ready_input</c>/<c>ready_output</c> is - <c>NULL</c>).</p> + <p>Creates a new port executing the same driver + code as the port creating the new port.</p> + <taglist> + <tag><c>port</c></tag> + <item>The port handle of the port (driver instance) creating + the new port.</item> + <tag><c>owner_pid</c></tag> + <item>The process ID of the Erlang process to become + owner of the new port. This process will be linked + to the new port. You usually want to use + <c>driver_caller(port)</c> as <c>owner_pid</c>.</item> + <tag><c>name</c></tag> + <item>The port name of the new port. You usually want to + use the same port name as the driver name + (<seealso marker="driver_entry#driver_name"> + <c>driver_name</c></seealso> field of the + <seealso marker="driver_entry"><c>driver_entry</c></seealso>). + </item> + <tag><c>drv_data</c></tag> + <item>The driver-defined handle that is passed in later + calls to driver callbacks. Notice that the + <seealso marker="driver_entry#start">driver start + callback</seealso> is not called for this new driver instance. + The driver-defined handle is normally created in the + <seealso marker="driver_entry#start">driver start callback</seealso> + when a port is created through + <seealso marker="erlang#open_port/2"> + <c>erlang:open_port/2</c></seealso>. + </item> + </taglist> + <p>The caller of <c>driver_create_port</c> is allowed to + manipulate the newly created port when <c>driver_create_port</c> + has returned. When + <seealso marker="#smp_support">port level locking</seealso> + is used, the creating port is only allowed to + manipulate the newly created port until the current driver + callback, which was called by the emulator, returns.</p> </desc> </func> + <func> - <name><ret>void *</ret><nametext>driver_alloc(ErlDrvSizeT size)</nametext></name> - <fsummary>Allocate memory</fsummary> + <name><ret>int</ret><nametext>driver_demonitor_process(ErlDrvPort port, + const ErlDrvMonitor *monitor)</nametext></name> + <fsummary>Stop monitoring a process from a driver.</fsummary> <desc> - <marker id="driver_alloc"></marker> - <p>This function allocates a memory block of the size specified - in <c>size</c>, and returns it. This only fails on out of - memory, in that case <c>NULL</c> is returned. (This is most - often a wrapper for <c>malloc</c>).</p> - <p>Memory allocated must be explicitly freed with a corresponding - call to <c>driver_free</c> (unless otherwise stated).</p> - <p>This function is thread-safe.</p> + <marker id="driver_demonitor_process"></marker> + <p>Cancels a monitor created earlier.</p> + <p>Returns <c>0</c> if a monitor was removed and > 0 if the monitor + no longer exists.</p> </desc> </func> + <func> - <name><ret>void *</ret><nametext>driver_realloc(void *ptr, ErlDrvSizeT size)</nametext></name> - <fsummary>Resize an allocated memory block</fsummary> + <name><ret>ErlDrvSizeT</ret><nametext>driver_deq(ErlDrvPort port, + ErlDrvSizeT size)</nametext></name> + <fsummary>Dequeue data from the head of the driver queue.</fsummary> <desc> - <marker id="driver_realloc"></marker> - <p>This function resizes a memory block, either in place, or by - allocating a new block, copying the data and freeing the old - block. A pointer is returned to the reallocated memory. On - failure (out of memory), <c>NULL</c> is returned. (This is - most often a wrapper for <c>realloc</c>.)</p> - <p>This function is thread-safe.</p> + <marker id="driver_deq"></marker> + <p>Dequeues data by moving the head pointer + forward in the driver queue by <c>size</c> bytes. The data + in the queue is deallocated.</p> + <p>Returns the number of bytes remaining in the queue on success, + otherwise <c>-1</c>.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>driver_free(void *ptr)</nametext></name> - <fsummary>Free an allocated memory block</fsummary> + <name><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, + ErlDrvSizeT len)</nametext></name> + <fsummary>Enqueue data in the driver queue.</fsummary> <desc> - <marker id="driver_free"></marker> - <p>This function frees the memory pointed to by <c>ptr</c>. The - memory should have been allocated with - <c>driver_alloc</c>. All allocated memory should be - deallocated, just once. There is no garbage collection in - drivers.</p> - <p>This function is thread-safe.</p> + <marker id="driver_enq"></marker> + <p>Enqueues data in the driver queue. The data in + <c>buf</c> is copied (<c>len</c> bytes) and placed at the + end of the driver queue. The driver queue is normally used + in a FIFO way.</p> + <p>The driver queue is available to queue output from the + emulator to the driver (data from the driver to the emulator + is queued by the emulator in normal Erlang message + queues). This can be useful if the driver must wait for + slow devices, and so on, and wants to yield back to the + emulator. The driver queue is implemented as an <c>ErlIOVec</c>.</p> + <p>When the queue contains data, the driver does not close until + the queue is empty.</p> + <p>The return value is <c>0</c>.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>ErlDrvBinary *</ret><nametext>driver_alloc_binary(ErlDrvSizeT size)</nametext></name> - <fsummary>Allocate a driver binary</fsummary> + <name><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, + ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext> + </name> + <fsummary>Enqueue binary in the driver queue.</fsummary> <desc> - <marker id="driver_alloc_binary"></marker> - <p>This function allocates a driver binary with a memory block - of at least <c>size</c> bytes, and returns a pointer to it, - or NULL on failure (out of memory). When a driver binary has - been sent to the emulator, it must not be altered. Every - allocated binary should be freed by a corresponding call to - <c>driver_free_binary</c> (unless otherwise stated).</p> - <p>Note that a driver binary has an internal reference counter, - this means that calling <c>driver_free_binary</c> it may not - actually dispose of it. If it's sent to the emulator, it may - be referenced there.</p> - <p>The driver binary has a field, <c>orig_bytes</c>, which - marks the start of the data in the binary.</p> - <p>This function is thread-safe.</p> + <marker id="driver_enq_bin"></marker> + <p>Enqueues a driver binary in the driver + queue. The data in <c>bin</c> at <c>offset</c> with length + <c>len</c> is placed at the end of the queue. This function + is most often faster than + <seealso marker="#driver_enq"><c>driver_enq</c></seealso>, + because no data must be copied.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> + <p>The return value is <c>0</c>.</p> </desc> </func> + <func> - <name><ret>ErlDrvBinary *</ret><nametext>driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size)</nametext></name> - <fsummary>Resize a driver binary</fsummary> + <name><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, + ErlDrvSizeT skip)</nametext></name> + <fsummary>Enqueue vector in the driver queue.</fsummary> <desc> - <marker id="driver_realloc_binary"></marker> - <p>This function resizes a driver binary, while keeping the - data. The resized driver binary is returned. On failure (out - of memory), <c>NULL</c> is returned.</p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> + <marker id="driver_enqv"></marker> + <p>Enqueues the data in <c>ev</c>, skipping the + first <c>skip</c> bytes of it, at the end of the driver + queue. It is faster than + <seealso marker="#driver_enq"><c>driver_enq</c></seealso>, + because no data must be copied.</p> + <p>The return value is <c>0</c>.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>driver_free_binary(ErlDrvBinary *bin)</nametext></name> - <fsummary>Free a driver binary</fsummary> + <name><ret>int</ret><nametext>driver_failure(ErlDrvPort port, int + error)</nametext></name> + <name><ret>int</ret><nametext>driver_failure_atom(ErlDrvPort port, char + *string)</nametext></name> + <name><ret>int</ret><nametext>driver_failure_posix(ErlDrvPort port, int + error)</nametext></name> + <fsummary>Fail with error.</fsummary> <desc> - <marker id="driver_free_binary"></marker> - <p>This function frees a driver binary <c>bin</c>, allocated - previously with <c>driver_alloc_binary</c>. Since binaries - in Erlang are reference counted, the binary may still be - around.</p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> + <marker id="driver_failure_atom"></marker> + <marker id="driver_failure_posix"></marker> + <marker id="driver_failure"></marker> + <p>Signals to Erlang that the driver has + encountered an error and is to be closed. The port is + closed and the tuple <c>{'EXIT', error, Err}</c> is sent to + the port owner process, where error is an error atom + (<c>driver_failure_atom</c> and + <c>driver_failure_posix</c>) or an integer + (<c>driver_failure</c>).</p> + <p>The driver is to fail only when in severe error situations, + when the driver cannot possibly keep open, for example, + buffer allocation gets out of memory. For normal errors + it is more appropriate to send error codes with + <seealso marker="#driver_output"><c>driver_output</c></seealso>.</p> + <p>The return value is <c>0</c>.</p> </desc> </func> + <func> - <name><ret>long</ret><nametext>driver_binary_get_refc(ErlDrvBinary *bin)</nametext></name> - <fsummary>Get the reference count of a driver binary</fsummary> + <name><ret>int</ret><nametext>driver_failure_eof(ErlDrvPort + port)</nametext></name> + <fsummary>Fail with EOF.</fsummary> <desc> - <marker id="driver_binary_get_refc"></marker> - <p>Returns current reference count on <c>bin</c>.</p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> + <marker id="driver_failure_eof"></marker> + <p>Signals to Erlang that the driver has + encountered an EOF and is to be closed, unless the port was + opened with option <c>eof</c>, in which case <c>eof</c> is sent + to the port. Otherwise the port is closed and an + <c>'EXIT'</c> message is sent to the port owner process.</p> + <p>The return value is <c>0</c>.</p> </desc> </func> + <func> - <name><ret>long</ret><nametext>driver_binary_inc_refc(ErlDrvBinary *bin)</nametext></name> - <fsummary>Increment the reference count of a driver binary</fsummary> + <name><ret>void</ret><nametext>driver_free(void *ptr)</nametext></name> + <fsummary>Free an allocated memory block.</fsummary> <desc> - <marker id="driver_binary_inc_refc"></marker> - <p>Increments the reference count on <c>bin</c> and returns - the reference count reached after the increment.</p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> + <marker id="driver_free"></marker> + <p>Frees the memory pointed to by <c>ptr</c>. The + memory is to have been allocated with + <c>driver_alloc</c>. All allocated memory is to be + deallocated, only once. There is no garbage collection in + drivers.</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>long</ret><nametext>driver_binary_dec_refc(ErlDrvBinary *bin)</nametext></name> - <fsummary>Decrement the reference count of a driver binary</fsummary> + <name><ret>void</ret> + <nametext>driver_free_binary(ErlDrvBinary *bin)</nametext></name> + <fsummary>Free a driver binary.</fsummary> <desc> - <marker id="driver_binary_dec_refc"></marker> - <p>Decrements the reference count on <c>bin</c> and returns - the reference count reached after the decrement.</p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> - <note> - <p>You should normally decrement the reference count of a - driver binary by calling - <seealso marker="#driver_free_binary">driver_free_binary()</seealso>. - <c>driver_binary_dec_refc()</c> does <em>not</em> free - the binary if the reference count reaches zero. <em>Only</em> - use <c>driver_binary_dec_refc()</c> when you are sure - <em>not</em> to reach a reference count of zero.</p> - </note> + <marker id="driver_free_binary"></marker> + <p>Frees a driver binary <c>bin</c>, allocated previously with + <seealso marker="#driver_alloc_binary"> + <c>driver_alloc_binary</c></seealso>. As binaries + in Erlang are reference counted, the binary can still be around.</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name> - <fsummary>Enqueue data in the driver queue</fsummary> + <name><ret>ErlDrvTermData</ret> + <nametext>driver_get_monitored_process(ErlDrvPort port, const + ErlDrvMonitor *monitor)</nametext></name> + <fsummary>Retrieve the process ID from a monitor.</fsummary> <desc> - <marker id="driver_enq"></marker> - <p>This function enqueues data in the driver queue. The data in - <c>buf</c> is copied (<c>len</c> bytes) and placed at the - end of the driver queue. The driver queue is normally used - in a FIFO way.</p> - <p>The driver queue is available to queue output from the - emulator to the driver (data from the driver to the emulator - is queued by the emulator in normal erlang message - queues). This can be useful if the driver has to wait for - slow devices etc, and wants to yield back to the - emulator. The driver queue is implemented as an ErlIOVec.</p> - <p>When the queue contains data, the driver won't close, until - the queue is empty.</p> - <p>The return value is 0.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_get_monitored_process"></marker> + <p>Returns the process ID associated with a living + monitor. It can be used in the + <seealso marker="driver_entry#process_exit"> + <c>process_exit</c></seealso> callback to + get the process identification for the exiting process.</p> + <p>Returns <c>driver_term_nil</c> if the monitor no longer exists.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name> - <fsummary>Push data at the head of the driver queue</fsummary> + <name><ret>int</ret> + <nametext>driver_get_now(ErlDrvNowData *now)</nametext></name> + <fsummary>Read a system time stamp.</fsummary> <desc> - <marker id="driver_pushq"></marker> - <p>This function puts data at the head of the driver queue. The - data in <c>buf</c> is copied (<c>len</c> bytes) and placed - at the beginning of the queue.</p> - <p>The return value is 0.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_get_now"></marker> + <warning> + <p><em>This function is deprecated. Do not use it.</em> Use + <seealso marker="#erl_drv_monotonic_time"> + <c>erl_drv_monotonic_time</c></seealso> (perhaps in combination with + <seealso marker="#erl_drv_time_offset"> + <c>erl_drv_time_offset</c></seealso>) instead.</p> + </warning> + <p>Reads a time stamp into the memory pointed to by + parameter <c>now</c>. For information about specific fields, see + <seealso marker="#ErlDrvNowData"><c>ErlDrvNowData</c></seealso>.</p> + <p>The return value is <c>0</c>, unless the <c>now</c> pointer is + invalid, in which case it is < <c>0</c>.</p> </desc> </func> + <func> - <name><ret>ErlDrvSizeT</ret><nametext>driver_deq(ErlDrvPort port, ErlDrvSizeT size)</nametext></name> - <fsummary>Dequeue data from the head of the driver queue</fsummary> + <name><ret>int</ret><nametext>driver_lock_driver(ErlDrvPort + port)</nametext></name> + <fsummary>Ensure the driver is never unloaded.</fsummary> <desc> - <marker id="driver_deq"></marker> - <p>This function dequeues data by moving the head pointer - forward in the driver queue by <c>size</c> bytes. The data - in the queue will be deallocated.</p> - <p>The return value is the number of bytes remaining in the queue - or -1 on failure.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_lock_driver"></marker> + <p>Locks the driver used by the port <c>port</c> + in memory for the rest of the emulator process' + lifetime. After this call, the driver behaves as one of Erlang's + statically linked-in drivers.</p> </desc> </func> + <func> - <name><ret>ErlDrvSizeT</ret><nametext>driver_sizeq(ErlDrvPort port)</nametext></name> - <fsummary>Return the size of the driver queue</fsummary> + <name><ret>ErlDrvTermData</ret><nametext>driver_mk_atom(char* + string)</nametext></name> + <fsummary>Make an atom from a name.</fsummary> <desc> - <marker id="driver_sizeq"></marker> - <p>This function returns the number of bytes currently in the - driver queue.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_mk_atom"></marker> + <p>Returns an atom given a name + <c>string</c>. The atom is created and does not change, so the + return value can be saved and reused, which is faster than + looking up the atom several times.</p> + <p>Notice that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name> - <fsummary>Enqueue binary in the driver queue</fsummary> + <name><ret>ErlDrvTermData</ret><nametext>driver_mk_port(ErlDrvPort + port)</nametext></name> + <fsummary>Make an Erlang term port from a port.</fsummary> <desc> - <marker id="driver_enq_bin"></marker> - <p>This function enqueues a driver binary in the driver - queue. The data in <c>bin</c> at <c>offset</c> with length - <c>len</c> is placed at the end of the queue. This function - is most often faster than <c>driver_enq</c>, because the - data doesn't have to be copied.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> - <p>The return value is 0.</p> + <marker id="driver_mk_port"></marker> + <p>Converts a port handle to the Erlang term format, usable in + <seealso marker="#erl_drv_output_term"> + <c>erl_drv_output_term</c></seealso> and + <seealso marker="#erl_drv_send_term"> + <c>erl_drv_send_term</c></seealso>.</p> + <p>Notice that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name> - <fsummary>Push binary at the head of the driver queue</fsummary> + <name><ret>int</ret><nametext>driver_monitor_process(ErlDrvPort port, + ErlDrvTermData process, ErlDrvMonitor *monitor)</nametext></name> + <fsummary>Monitor a process from a driver.</fsummary> <desc> - <marker id="driver_pushq_bin"></marker> - <p>This function puts data in the binary <c>bin</c>, at - <c>offset</c> with length <c>len</c> at the head of the - driver queue. It is most often faster than - <c>driver_pushq</c>, because the data doesn't have to be - copied.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> - <p>The return value is 0.</p> + <marker id="driver_monitor_process"></marker> + <p>Starts monitoring a process from a driver. When a process is + monitored, a process exit results in a call to the provided + <seealso marker="driver_entry#process_exit"> + <c>process_exit</c></seealso> callback + in the <seealso marker="driver_entry"><c>ErlDrvEntry</c></seealso> + structure. The <c>ErlDrvMonitor</c> structure is filled in, for later + removal or compare.</p> + <p>Parameter <c>process</c> is to be the return value of an + earlier call to <seealso marker="#driver_caller"> + <c>driver_caller</c></seealso> or + <seealso marker="#driver_connected"><c>driver_connected</c></seealso> + call.</p> + <p>Returns <c>0</c> on success, < 0 if no callback is + provided, and > 0 if the process is no longer alive.</p> </desc> </func> + <func> - <name><ret>ErlDrvSizeT</ret><nametext>driver_peekqv(ErlDrvPort port, ErlIOVec *ev)</nametext></name> - <fsummary>Get the driver queue as an IO vector</fsummary> + <name><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, + ErlDrvSizeT len)</nametext></name> + <fsummary>Send data from driver to port owner.</fsummary> <desc> - <marker id="driver_peekqv"></marker> - <p> - This function retrieves the driver queue into a supplied - <c>ErlIOVec</c> <c>ev</c>. It also returns the queue size. - This is one of two ways to get data out of the queue. - </p> - <p> - If <c>ev</c> is <c>NULL</c> all ones i.e. <c>-1</c> type cast to - <c>ErlDrvSizeT</c> is returned. - </p> - <p>Nothing is removed from the queue by this function, that must be done - with <c>driver_deq</c>.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_output"></marker> + <p>Sends data from the driver up to the emulator. The data is received + as terms or binary data, depending on how the driver port was + opened.</p> + <p>The data is queued in the port owner process' message + queue. Notice that this does not yield to the emulator (as + the driver and the emulator run in the same thread).</p> + <p>Parameter <c>buf</c> points to the data to send, and + <c>len</c> is the number of bytes.</p> + <p>The return value for all output functions is <c>0</c> for normal use. + If the driver is used for distribution, it can fail and return + <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>SysIOVec *</ret><nametext>driver_peekq(ErlDrvPort port, int *vlen)</nametext></name> - <fsummary>Get the driver queue as a vector</fsummary> + <name><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char + *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, + ErlDrvSizeT len)</nametext></name> + <fsummary>Send data from a driver binary to port owner.</fsummary> <desc> - <marker id="driver_peekq"></marker> - <p>This function retrieves the driver queue as a pointer to an - array of <c>SysIOVec</c>s. It also returns the number of - elements in <c>vlen</c>. This is one of two ways to get data - out of the queue.</p> - <p>Nothing is removed from the queue by this function, that must be done - with <c>driver_deq</c>.</p> - <p>The returned array is suitable to use with the Unix system - call <c>writev</c>.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_output_binary"></marker> + <p>Sends data to a port owner process from a + driver binary. It has a header buffer (<c>hbuf</c> + and <c>hlen</c>) just like + <seealso marker="#driver_output2"><c>driver_output2</c></seealso>. + Parameter <c>hbuf</c> can be <c>NULL</c>.</p> + <p>Parameter <c>offset</c> is an offset into the binary and + <c>len</c> is the number of bytes to send.</p> + <p>Driver binaries are created with + <seealso marker="#driver_alloc_binary"> + <c>driver_alloc_binary</c></seealso>.</p> + <p>The data in the header is sent as a list and the binary as + an Erlang binary in the tail of the list.</p> + <p>For example, if <c>hlen</c> is <c>2</c>, the port owner process + receives <c><![CDATA[[H1, H2 | <<T>>]]]></c>.</p> + <p>The return value is <c>0</c> for normal use.</p> + <p>Notice that, using the binary syntax in Erlang, the driver + application can match the header directly from the binary, + so the header can be put in the binary, and <c>hlen</c> can be set + to <c>0</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name> - <fsummary>Enqueue vector in the driver queue</fsummary> + <name><ret>int</ret><nametext>driver_output_term(ErlDrvPort port, + ErlDrvTermData* term, int n)</nametext></name> + <fsummary>Send term data from driver to port owner.</fsummary> <desc> - <marker id="driver_enqv"></marker> - <p>This function enqueues the data in <c>ev</c>, skipping the - first <c>skip</c> bytes of it, at the end of the driver - queue. It is faster than <c>driver_enq</c>, because the data - doesn't have to be copied.</p> - <p>The return value is 0.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_output_term"></marker> + <warning> + <p><em>This function is deprecated.</em> + Use <seealso marker="#erl_drv_send_term"> + <c>erl_drv_output_term</c></seealso>instead.</p> + </warning> + <p>Parameters <c>term</c> and <c>n</c> work as in + <seealso marker="#erl_drv_output_term"> + <c>erl_drv_output_term</c></seealso>.</p> + <p>Notice that this function is <em>not</em> thread-safe, not + even when the emulator with SMP support is used.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name> - <fsummary>Push vector at the head of the driver queue</fsummary> + <name><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, + ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)</nametext></name> + <fsummary>Send data and binary data to port owner.</fsummary> <desc> - <marker id="driver_pushqv"></marker> - <p>This function puts the data in <c>ev</c>, skipping the first - <c>skip</c> bytes of it, at the head of the driver queue. - It is faster than <c>driver_pushq</c>, because the data - doesn't have to be copied.</p> - <p>The return value is 0.</p> - <p>This function can be called from an arbitrary thread if a - <seealso marker="#ErlDrvPDL">port data lock</seealso> - associated with the <c>port</c> is locked by the calling - thread during the call.</p> + <marker id="driver_output2"></marker> + <p>First sends <c>hbuf</c> + (length in <c>hlen</c>) data as a list, regardless of port + settings. Then sends <c>buf</c> as a binary or list. + For example, if <c>hlen</c> is <c>3</c>, the port owner process + receives <c>[H1, H2, H3 | T]</c>.</p> + <p>The point of sending data as a list header, is to facilitate + matching on the data received.</p> + <p>The return value is <c>0</c> for normal use.</p> </desc> </func> + <func> - <name><ret>ErlDrvPDL</ret><nametext>driver_pdl_create(ErlDrvPort port)</nametext></name> - <fsummary>Create a port data lock</fsummary> + <name><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, + ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name> + <fsummary>Send vectorized data to port owner.</fsummary> <desc> - <marker id="driver_pdl_create"></marker> - <p>This function creates a port data lock associated with - the <c>port</c>. <em>NOTE</em>: Once a port data lock has - been created, it has to be locked during all operations - on the driver queue of the <c>port</c>.</p> - <p>On success a newly created port data lock is returned. On - failure <c>NULL</c> is returned. <c>driver_pdl_create()</c> will - fail if <c>port</c> is invalid or if a port data lock already has - been associated with the <c>port</c>.</p> + <marker id="driver_outputv"></marker> + <p>Sends data from an I/O vector, <c>ev</c>, to + the port owner process. It has a header buffer (<c>hbuf</c> + and <c>hlen</c>), just like <seealso marker="#driver_output2"> + <c>driver_output2</c></seealso>.</p> + <p>Parameter <c>skip</c> is a number of bytes to skip of + the <c>ev</c> vector from the head.</p> + <p>You get vectors of <c>ErlIOVec</c> type from the driver + queue (see below), and the + <seealso marker="driver_entry#outputv"><c>outputv</c></seealso> + driver entry function. You can also make them yourself, if you want to + send several <c>ErlDrvBinary</c> buffers at once. Often + it is faster to use + <seealso marker="#driver_output"><c>driver_output</c></seealso> or + <seealso marker="#driver_output_binary"></seealso>.</p> + <p>For example, if <c>hlen</c> is <c>2</c> and <c>ev</c> points to an + array of three binaries, the port owner process receives + <c><![CDATA[[H1, H2, <<B1>>, <<B2>> | <<B3>>]]]></c>.</p> + <p>The return value is <c>0</c> for normal use.</p> + <p>The comment for <c>driver_output_binary</c> also applies for + <c>driver_outputv</c>.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>driver_pdl_lock(ErlDrvPDL pdl)</nametext></name> - <fsummary>Lock port data lock</fsummary> + <name><ret>ErlDrvPDL</ret> + <nametext>driver_pdl_create(ErlDrvPort port)</nametext></name> + <fsummary>Create a port data lock.</fsummary> <desc> - <marker id="driver_pdl_lock"></marker> - <p>This function locks the port data lock passed as argument - (<c>pdl</c>).</p> - <p>This function is thread-safe.</p> + <marker id="driver_pdl_create"></marker> + <p>Creates a port data lock associated with the <c>port</c>.</p> + <note> + <p>Once a port data lock has been created, it must be locked during + all operations on the driver queue of the <c>port</c>.</p> + </note> + <p>Returns a newly created port data lock on success, + otherwise <c>NULL</c>. The function fails + if <c>port</c> is invalid or if a port data lock already has + been associated with the <c>port</c>.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>driver_pdl_unlock(ErlDrvPDL pdl)</nametext></name> - <fsummary>Unlock port data lock</fsummary> + <name><ret>long</ret><nametext>driver_pdl_dec_refc(ErlDrvPDL + pdl)</nametext></name> + <fsummary></fsummary> <desc> - <marker id="driver_pdl_unlock"></marker> - <p>This function unlocks the port data lock passed as argument - (<c>pdl</c>).</p> + <marker id="driver_pdl_dec_refc"></marker> + <p>Decrements the reference count of + the port data lock passed as argument (<c>pdl</c>).</p> + <p>The current reference count after the decrement has + been performed is returned.</p> <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>long</ret><nametext>driver_pdl_get_refc(ErlDrvPDL pdl)</nametext></name> + <name><ret>long</ret> + <nametext>driver_pdl_get_refc(ErlDrvPDL pdl)</nametext></name> <fsummary></fsummary> <desc> <marker id="driver_pdl_get_refc"></marker> - <p>This function returns the current reference count of + <p>Returns the current reference count of the port data lock passed as argument (<c>pdl</c>).</p> <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>long</ret><nametext>driver_pdl_inc_refc(ErlDrvPDL pdl)</nametext></name> + <name><ret>long</ret> + <nametext>driver_pdl_inc_refc(ErlDrvPDL pdl)</nametext></name> <fsummary></fsummary> <desc> <marker id="driver_pdl_inc_refc"></marker> - <p>This function increments the reference count of + <p>Increments the reference count of the port data lock passed as argument (<c>pdl</c>).</p> <p>The current reference count after the increment has been performed is returned.</p> <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>long</ret><nametext>driver_pdl_dec_refc(ErlDrvPDL pdl)</nametext></name> - <fsummary></fsummary> + <name><ret>void</ret> + <nametext>driver_pdl_lock(ErlDrvPDL pdl)</nametext></name> + <fsummary>Lock port data lock.</fsummary> <desc> - <marker id="driver_pdl_dec_refc"></marker> - <p>This function decrements the reference count of - the port data lock passed as argument (<c>pdl</c>).</p> - <p>The current reference count after the decrement has - been performed is returned.</p> + <marker id="driver_pdl_lock"></marker> + <p>Locks the port data lock passed as argument (<c>pdl</c>).</p> <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_monitor_process(ErlDrvPort port, ErlDrvTermData process, ErlDrvMonitor *monitor)</nametext></name> - <fsummary>Monitor a process from a driver</fsummary> + <name><ret>void</ret> + <nametext>driver_pdl_unlock(ErlDrvPDL pdl)</nametext></name> + <fsummary>Unlock port data lock.</fsummary> <desc> - <marker id="driver_monitor_process"></marker> - <p>Start monitoring a process from a driver. When a process is - monitored, a process exit will result in a call to the - provided <seealso marker="driver_entry#process_exit">process_exit</seealso> call-back - in the <seealso marker="driver_entry">ErlDrvEntry</seealso> - structure. The <c>ErlDrvMonitor</c> structure is filled in, for later - removal or compare.</p> - <p>The <c>process</c> parameter should be the return value of an - earlier call to <seealso marker="#driver_caller">driver_caller</seealso> or <seealso marker="#driver_connected">driver_connected</seealso> call.</p> - <p>The function returns 0 on success, < 0 if no call-back is - provided and > 0 if the process is no longer alive.</p> + <marker id="driver_pdl_unlock"></marker> + <p>Unlocks the port data lock passed as argument (<c>pdl</c>).</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor)</nametext></name> - <fsummary>Stop monitoring a process from a driver</fsummary> + <name><ret>SysIOVec *</ret><nametext>driver_peekq(ErlDrvPort port, int + *vlen)</nametext></name> + <fsummary>Get the driver queue as a vector.</fsummary> <desc> - <marker id="driver_demonitor_process"></marker> - <p>This function cancels a monitor created earlier. </p> - <p>The function returns 0 if a monitor was removed and > 0 - if the monitor did no longer exist.</p> + <marker id="driver_peekq"></marker> + <p>Retrieves the driver queue as a pointer to an + array of <c>SysIOVec</c>s. It also returns the number of + elements in <c>vlen</c>. This is one of two ways to get data + out of the queue.</p> + <p>Nothing is removed from the queue by this function, that must be done + with <seealso marker="#driver_deq"><c>driver_deq</c></seealso>.</p> + <p>The returned array is suitable to use with the Unix system + call <c>writev</c>.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor)</nametext></name> - <fsummary>Retrieve the process id from a monitor</fsummary> + <name><ret>ErlDrvSizeT</ret><nametext>driver_peekqv(ErlDrvPort port, + ErlIOVec *ev)</nametext></name> + <fsummary>Get the driver queue as an I/O vector.</fsummary> <desc> - <marker id="driver_get_monitored_process"></marker> - <p>The function returns the process id associated with a living - monitor. It can be used in the <c>process_exit</c> call-back to - get the process identification for the exiting process.</p> - <p>The function returns <c>driver_term_nil</c> if the monitor - no longer exists.</p> + <marker id="driver_peekqv"></marker> + <p>Retrieves the driver queue into a supplied + <c>ErlIOVec</c> <c>ev</c>. It also returns the queue size. + This is one of two ways to get data out of the queue.</p> + <p>If <c>ev</c> is <c>NULL</c>, all ones that is <c>-1</c> type cast to + <c>ErlDrvSizeT</c> are returned.</p> + <p>Nothing is removed from the queue by this function, that must be done + with <seealso marker="#driver_deq"><c>driver_deq</c></seealso>.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2)</nametext></name> - <fsummary>Compare two monitors</fsummary> + <name><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, + ErlDrvSizeT len)</nametext></name> + <fsummary>Push data at the head of the driver queue.</fsummary> <desc> - <marker id="driver_compare_monitors"></marker> - <p>This function is used to compare two <c>ErlDrvMonitor</c>s. It - can also be used to imply some artificial order on monitors, - for whatever reason.</p> - <p>The function returns 0 if <c>monitor1</c> and - <c>monitor2</c> are equal, < 0 if <c>monitor1</c> is less - than <c>monitor2</c> and > 0 if <c>monitor1</c> is greater - than <c>monitor2</c>.</p> + <marker id="driver_pushq"></marker> + <p>Puts data at the head of the driver queue. The + data in <c>buf</c> is copied (<c>len</c> bytes) and placed + at the beginning of the queue.</p> + <p>The return value is <c>0</c>.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>add_driver_entry(ErlDrvEntry *de)</nametext></name> - <fsummary>Add a driver entry</fsummary> + <name><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, + ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext> + </name> + <fsummary>Push binary at the head of the driver queue.</fsummary> <desc> - <marker id="add_driver_entry"></marker> - <p>This function adds a driver entry to the list of drivers - known by Erlang. The <seealso marker="driver_entry#init">init</seealso> function of the <c>de</c> - parameter is called.</p> - <note> - <p>To use this function for adding drivers residing in - dynamically loaded code is dangerous. If the driver code - for the added driver resides in the same dynamically - loaded module (i.e. <c>.so</c> file) as a normal - dynamically loaded driver (loaded with the <c>erl_ddll</c> - interface), the caller should call <seealso marker="#driver_lock_driver">driver_lock_driver</seealso> before - adding driver entries.</p> - <p>Use of this function is generally deprecated.</p> - </note> + <marker id="driver_pushq_bin"></marker> + <p>Puts data in the binary <c>bin</c>, at + <c>offset</c> with length <c>len</c> at the head of the + driver queue. It is most often faster than + <seealso marker="#driver_pushq"><c>driver_pushq</c></seealso>, + because no data must be copied.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> + <p>The return value is <c>0</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>remove_driver_entry(ErlDrvEntry *de)</nametext></name> - <fsummary>Remove a driver entry</fsummary> + <name><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec + *ev, ErlDrvSizeT skip)</nametext></name> + <fsummary>Push vector at the head of the driver queue.</fsummary> <desc> - <marker id="remove_driver_entry"></marker> - <p>This function removes a driver entry <c>de</c> previously - added with <c>add_driver_entry</c>.</p> - <p>Driver entries added by the <c>erl_ddll</c> erlang interface can - not be removed by using this interface.</p> + <marker id="driver_pushqv"></marker> + <p>Puts the data in <c>ev</c>, skipping the first + <c>skip</c> bytes of it, at the head of the driver queue. + It is faster than + <seealso marker="#driver_pushq"><c>driver_pushq</c></seealso>, + because no data must be copied.</p> + <p>The return value is <c>0</c>.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>char *</ret><nametext>erl_errno_id(int error)</nametext></name> - <fsummary>Get erlang error atom name from error number</fsummary> + <name><ret>int</ret><nametext>driver_read_timer(ErlDrvPort port, unsigned + long *time_left)</nametext></name> + <fsummary>Read the time left before time-out.</fsummary> <desc> - <marker id="erl_errno_id"></marker> - <p>This function returns the atom name of the erlang error, - given the error number in <c>error</c>. Error atoms are: - <c>einval</c>, <c>enoent</c>, etc. It can be used to make - error terms from the driver.</p> + <marker id="driver_read_timer"></marker> + <p>Reads the current time of a timer, and places + the result in <c>time_left</c>. This is the time in + milliseconds, before the time-out occurs.</p> + <p>The return value is <c>0</c>.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>erl_drv_busy_msgq_limits(ErlDrvPort port, ErlDrvSizeT *low, ErlDrvSizeT *high)</nametext></name> - <fsummary>Set and get limits for busy port message queue</fsummary> - <desc> - <marker id="erl_drv_busy_msgq_limits"></marker> - <p>Sets and gets limits that will be used for controling the - busy state of the port message queue.</p> - <p>The port message queue will be set into a busy - state when the amount of command data queued on the - message queue reaches the <c>high</c> limit. The port - message queue will be set into a not busy state when the - amount of command data queued on the message queue falls - below the <c>low</c> limit. Command data is in this - context data passed to the port using either - <c>Port ! {Owner, {command, Data}}</c>, or - <c>port_command/[2,3]</c>. Note that these limits - only concerns command data that have not yet reached the - port. The <seealso marker="#set_busy_port">busy port</seealso> - feature can be used for data that has reached the port.</p> - - <p>Valid limits are values in the range - <c>[ERL_DRV_BUSY_MSGQ_LIM_MIN, ERL_DRV_BUSY_MSGQ_LIM_MAX]</c>. - Limits will be automatically adjusted to be sane. That is, - the system will adjust values so that the low limit used is - lower than or equal to the high limit used. By default the high - limit will be 8 kB and the low limit will be 4 kB.</p> - - <p>By passing a pointer to an integer variable containing - the value <c>ERL_DRV_BUSY_MSGQ_READ_ONLY</c>, currently used - limit will be read and written back to the integer variable. - A new limit can be set by passing a pointer to an integer - variable containing a valid limit. The passed value will be - written to the internal limit. The internal limit will then - be adjusted. After this the adjusted limit will be written - back to the integer variable from which the new value was - read. Values are in bytes.</p> - - <p>The busy message queue feature can be disabled either - by setting the <c>ERL_DRV_FLAG_NO_BUSY_MSGQ</c> - <seealso marker="driver_entry#driver_flags">driver flag</seealso> - in the <seealso marker="driver_entry">driver_entry</seealso> - used by the driver, or by calling this function with - <c>ERL_DRV_BUSY_MSGQ_DISABLED</c> as a limit (either low or - high). When this feature has been disabled it cannot be - enabled again. When reading the limits both of them - will be <c>ERL_DRV_BUSY_MSGQ_DISABLED</c>, if this - feature has been disabled.</p> - - <p>Processes sending command data to the port will be suspended - if either the port is busy or if the port message queue is - busy. Suspended processes will be resumed when neither the - port is busy, nor the port message queue is busy.</p> - - <p>For information about busy port functionality - see the documentation of the - <seealso marker="#set_busy_port">set_busy_port()</seealso> - function.</p> - </desc> - </func> - <func> - <name><ret>void</ret><nametext>set_busy_port(ErlDrvPort port, int on)</nametext></name> - <fsummary>Signal or unsignal port as busy</fsummary> + <name><ret>void *</ret> + <nametext>driver_realloc(void *ptr, ErlDrvSizeT size)</nametext></name> + <fsummary>Resize an allocated memory block.</fsummary> <desc> - <marker id="set_busy_port"></marker> - <p>This function set and unset the busy state of the port. If - <c>on</c> is non-zero, the port is set to busy, if it's zero the port - is set to not busy. You typically want to combine - this feature with the <seealso marker="#erl_drv_busy_msgq_limits">busy - port message queue</seealso> functionality.</p> - <p>Processes sending command data to the port will be suspended - if either the port is busy or if the port message queue - is busy. Suspended processes will be resumed when neither the - port is busy, nor the port message queue is busy. Command data - is in this context data passed to the port using either - <c>Port ! {Owner, {command, Data}}</c>, or - <c>port_command/[2,3]</c>.</p> - <p>If the - <seealso marker="driver_entry#driver_flags"><![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso> - has been set in the - <seealso marker="driver_entry">driver_entry</seealso>, - data can be forced into the driver via - <seealso marker="erlang#port_command/3">port_command(Port, Data, [force])</seealso> - even though the driver has signaled that it is busy. - </p> - <p>For information about busy port message queue functionality - see the documentation of the - <seealso marker="#erl_drv_busy_msgq_limits">erl_drv_busy_msgq_limits()</seealso> - function.</p> - </desc> - </func> - <func> - <name><ret>void</ret><nametext>set_port_control_flags(ErlDrvPort port, int flags)</nametext></name> - <fsummary>Set flags on how to handle control entry function</fsummary> - <desc> - <marker id="set_port_control_flags"></marker> - <p>This function sets flags for how the <seealso marker="driver_entry#control">control</seealso> driver entry - function will return data to the port owner process. (The - <c>control</c> function is called from <c>port_control/3</c> - in erlang.)</p> - <p>Currently there are only two meaningful values for - <c>flags</c>: 0 means that data is returned in a list, and - <c>PORT_CONTROL_FLAG_BINARY</c> means data is returned as - a binary from <c>control</c>.</p> + <marker id="driver_realloc"></marker> + <p>Resizes a memory block, either in place, or by + allocating a new block, copying the data, and freeing the old + block. A pointer is returned to the reallocated memory. On + failure (out of memory), <c>NULL</c> is returned. (This is + most often a wrapper for <c>realloc</c>.)</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_failure_eof(ErlDrvPort port)</nametext></name> - <fsummary>Fail with EOF</fsummary> + <name><ret>ErlDrvBinary *</ret> + <nametext>driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size) + </nametext></name> + <fsummary>Resize a driver binary.</fsummary> <desc> - <marker id="driver_failure_eof"></marker> - <p>This function signals to erlang that the driver has - encountered an EOF and should be closed, unless the port was - opened with the <c>eof</c> option, in that case eof is sent - to the port. Otherwise, the port is closed and an - <c>'EXIT'</c> message is sent to the port owner process.</p> - <p>The return value is 0.</p> + <marker id="driver_realloc_binary"></marker> + <p>Resizes a driver binary, while keeping the data.</p> + <p>Returns the resized driver binary on success. Returns <c>NULL</c> + on failure (out of memory).</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_failure_atom(ErlDrvPort port, char *string)</nametext></name> - <name><ret>int</ret><nametext>driver_failure_posix(ErlDrvPort port, int error)</nametext></name> - <name><ret>int</ret><nametext>driver_failure(ErlDrvPort port, int error)</nametext></name> - <fsummary>Fail with error</fsummary> + <name><ret>int</ret><nametext>driver_select(ErlDrvPort port, ErlDrvEvent + event, int mode, int on)</nametext></name> + <fsummary>Provides an event for having the emulator call the driver. + </fsummary> <desc> - <marker id="driver_failure_atom"></marker> - <marker id="driver_failure_posix"></marker> - <marker id="driver_failure"></marker> - <p>These functions signal to Erlang that the driver has - encountered an error and should be closed. The port is - closed and the tuple <c>{'EXIT', error, Err}</c>, is sent to - the port owner process, where error is an error atom - (<c>driver_failure_atom</c> and - <c>driver_failure_posix</c>), or an integer - (<c>driver_failure</c>).</p> - <p>The driver should fail only when in severe error situations, - when the driver cannot possibly keep open, for instance - buffer allocation gets out of memory. For normal errors - it is more appropriate to send error codes with - <c>driver_output</c>.</p> - <p>The return value is 0.</p> + <marker id="driver_select"></marker> + <p>This function is used by drivers to provide the emulator with + events to check for. This enables the emulator to call the driver + when something has occurred asynchronously.</p> + <p>Parameter <c>event</c> identifies an OS-specific event object. + On Unix systems, the functions <c>select</c>/<c>poll</c> are used. + The event object must be a socket or pipe (or other object that + <c>select</c>/<c>poll</c> can use). + On Windows, the Win32 API function <c>WaitForMultipleObjects</c> + is used. This places other restrictions on the event object; + see the Win32 SDK documentation.</p> + <p>Parameter <c>on</c> is to be <c>1</c> for setting events + and <c>0</c> for clearing them.</p> + <p>Parameter <c>mode</c> is a bitwise OR combination of + <c>ERL_DRV_READ</c>, <c>ERL_DRV_WRITE</c>, and <c>ERL_DRV_USE</c>. + The first two specify whether to wait for read events and/or write + events. A fired read event calls + <seealso marker="driver_entry#ready_input"> + <c>ready_input</c></seealso> and a fired write event calls + <seealso marker="driver_entry#ready_output"> + <c>ready_output</c></seealso>.</p> + <note> + <p>Some OS (Windows) do not differentiate between read and write + events. The callback for a fired event then only depends on the + value of <c>mode</c>.</p> + </note> + <p><c>ERL_DRV_USE</c> specifies if we are using the event object or + if we want to close it. + On an emulator with SMP support, it is not safe to clear all events + and then close the event object after <c>driver_select</c> has + returned. Another thread can still be using the event object + internally. To safely close an event object, call + <c>driver_select</c> with <c>ERL_DRV_USE</c> and <c>on==0</c>, which + clears all events and then either calls + <seealso marker="driver_entry#stop_select"><c>stop_select</c></seealso> + or schedules it to be called when it is safe to close the event + object. <c>ERL_DRV_USE</c> is to be set together with the first event + for an event object. It is harmless to set <c>ERL_DRV_USE</c> + even if it already has been done. Clearing all events but keeping + <c>ERL_DRV_USE</c> set indicates that we are using the event + object and probably will set events for it again.</p> + <note> + <p><c>ERL_DRV_USE</c> was added in Erlang/OTP R13. Old drivers still + work as before, but it is recommended to update them to use + <c>ERL_DRV_USE</c> and <c>stop_select</c> to ensure that event + objects are closed in a safe way.</p> + </note> + <p>The return value is <c>0</c>, unless + <c>ready_input</c>/<c>ready_output</c> is <c>NULL</c>, in which case + it is <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_connected(ErlDrvPort port)</nametext></name> - <fsummary>Return the port owner process</fsummary> + <name><ret>int</ret><nametext>driver_send_term(ErlDrvPort port, + ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> + <fsummary>Send term data to other process than port owner process. + </fsummary> <desc> - <marker id="driver_connected"></marker> - <p>This function returns the port owner process.</p> - <p>Note that this function is <em>not</em> thread-safe, not - even when the emulator with SMP support is used.</p> + <marker id="driver_send_term"></marker> + <warning> + <p><em>This function is deprecated.</em> + Use <seealso marker="#erl_drv_send_term"> + <c>erl_drv_send_term</c></seealso> instead.</p> + </warning> + <note> + <p>The parameters of this function + cannot be properly checked by the runtime system when + executed by arbitrary threads. This can cause the + function not to fail when it should.</p> + </note> + <p>Parameters <c>term</c> and <c>n</c> work as in + <seealso marker="#erl_drv_output_term"> + <c>erl_drv_output_term</c></seealso>.</p> + <p>This function is only thread-safe when the emulator with SMP + support is used.</p> </desc> </func> + <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_caller(ErlDrvPort port)</nametext></name> - <fsummary>Return the process making the driver call</fsummary> + <name><ret>int</ret><nametext>driver_set_timer(ErlDrvPort port, unsigned + long time)</nametext></name> + <fsummary>Set a timer to call the driver.</fsummary> <desc> - <marker id="driver_caller"></marker> - <p>This function returns the process id of the process that - made the current call to the driver. The process id can be - used with <c>driver_send_term</c> to send back data to the - caller. <c>driver_caller()</c> only returns valid data - when currently executing in one of the following driver - callbacks:</p> - <taglist> - <tag><seealso marker="driver_entry#start">start</seealso></tag> - <item>Called from <c>open_port/2</c>.</item> - <tag><seealso marker="driver_entry#output">output</seealso></tag> - <item>Called from <c>erlang:send/2</c>, and - <c>erlang:port_command/2</c></item> - <tag><seealso marker="driver_entry#outputv">outputv</seealso></tag> - <item>Called from <c>erlang:send/2</c>, and - <c>erlang:port_command/2</c></item> - <tag><seealso marker="driver_entry#control">control</seealso></tag> - <item>Called from <c>erlang:port_control/3</c></item> - <tag><seealso marker="driver_entry#call">call</seealso></tag> - <item>Called from <c>erlang:port_call/3</c></item> - </taglist> - <p>Note that this function is <em>not</em> thread-safe, not - even when the emulator with SMP support is used.</p> + <marker id="driver_set_timer"></marker> + <p>Sets a timer on the driver, which will count + down and call the driver when it is timed out. Parameter + <c>time</c> is the time in milliseconds before the timer expires.</p> + <p>When the timer reaches <c>0</c> and expires, the driver entry + function <seealso marker="driver_entry#timeout"> + <c>timeout</c></seealso> is called.</p> + <p>Notice that only one timer exists on each driver instance; + setting a new timer replaces an older one.</p> + <p>Return value is <c>0</c>, unless the <c>timeout</c> + driver function is <c>NULL</c>, in which case it is <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>erl_drv_output_term(ErlDrvTermData port, ErlDrvTermData* term, int n)</nametext></name> - <fsummary>Send term data from driver to port owner</fsummary> + <name><ret>ErlDrvSizeT</ret> + <nametext>driver_sizeq(ErlDrvPort port)</nametext></name> + <fsummary>Return the size of the driver queue.</fsummary> <desc> - <marker id="erl_drv_output_term"></marker> - <p>This functions sends data in the special driver term - format to the port owner process. This is a fast way to - deliver term data from a driver. It also needs no binary - conversion, so the port owner process receives data as - normal Erlang terms. The - <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> - functions can be used for sending to any arbitrary process - on the local node.</p> - <note><p>Note that the <c>port</c> parameter is <em>not</em> - an ordinary port handle, but a port handle converted using - <c>driver_mk_port()</c>.</p></note> - <p>The <c>term</c> parameter points to an array of - <c>ErlDrvTermData</c>, with <c>n</c> elements. This array - contains terms described in the driver term format. Every - term consists of one to four elements in the array. The - term first has a term type, and then arguments. The - <c>port</c> parameter specifies the sending port.</p> - <p>Tuples, maps and lists (with the exception of strings, see below), - are built in reverse polish notation, so that to build a - tuple, the elements are given first, and then the tuple - term, with a count. Likewise for lists and maps.</p> - <p>A tuple must be specified with the number of elements. (The - elements precede the <c>ERL_DRV_TUPLE</c> term.)</p> - <p>A list must be specified with the number of elements, - including the tail, which is the last term preceding - <c>ERL_DRV_LIST</c>.</p> - <p>A map must be specified with the number of key-value pairs <c>N</c>. - The key-value pairs must precede the <c>ERL_DRV_MAP</c> in this order: - <c>key1,value1,key2,value2,...,keyN,valueN</c>. - Duplicate keys are not allowed.</p> - <p>The special term <c>ERL_DRV_STRING_CONS</c> is used to - "splice" in a string in a list, a string given this way is - not a list per se, but the elements are elements of the - surrounding list.</p> - <pre> -Term type Argument(s) -=========================================== -ERL_DRV_NIL -ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string)) -ERL_DRV_INT ErlDrvSInt integer -ERL_DRV_UINT ErlDrvUInt integer -ERL_DRV_INT64 ErlDrvSInt64 *integer_ptr -ERL_DRV_UINT64 ErlDrvUInt64 *integer_ptr -ERL_DRV_PORT ErlDrvTermData port (from driver_mk_port(ErlDrvPort port)) -ERL_DRV_BINARY ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset -ERL_DRV_BUF2BINARY char *buf, ErlDrvUInt len -ERL_DRV_STRING char *str, int len -ERL_DRV_TUPLE int sz -ERL_DRV_LIST int sz -ERL_DRV_PID ErlDrvTermData pid (from driver_connected(ErlDrvPort port) or driver_caller(ErlDrvPort port)) -ERL_DRV_STRING_CONS char *str, int len -ERL_DRV_FLOAT double *dbl -ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len -ERL_DRV_MAP int sz - </pre> - <p>The unsigned integer data type <c>ErlDrvUInt</c> and the - signed integer data type <c>ErlDrvSInt</c> are 64 bits wide - on a 64 bit runtime system and 32 bits wide on a 32 bit - runtime system. They were introduced in erts version 5.6, - and replaced some of the <c>int</c> arguments in the list above. - </p> - <p>The unsigned integer data type <c>ErlDrvUInt64</c> and the - signed integer data type <c>ErlDrvSInt64</c> are always 64 bits - wide. They were introduced in erts version 5.7.4. - </p> - - <p>To build the tuple <c>{tcp, Port, [100 | Binary]}</c>, the - following call could be made.</p> - <code type="none"><![CDATA[ - ErlDrvBinary* bin = ... - ErlDrvPort port = ... - ErlDrvTermData spec[] = { - ERL_DRV_ATOM, driver_mk_atom("tcp"), - ERL_DRV_PORT, driver_mk_port(drvport), - ERL_DRV_INT, 100, - ERL_DRV_BINARY, bin, 50, 0, - ERL_DRV_LIST, 2, - ERL_DRV_TUPLE, 3, - }; - erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); - ]]> - </code> - <p>Where <c>bin</c> is a driver binary of length at least 50 - and <c>drvport</c> is a port handle. Note that the <c>ERL_DRV_LIST</c> - comes after the elements of the list, likewise the - <c>ERL_DRV_TUPLE</c>.</p> - <p>The term <c>ERL_DRV_STRING_CONS</c> is a way to construct - strings. It works differently from how <c>ERL_DRV_STRING</c> - works. <c>ERL_DRV_STRING_CONS</c> builds a string list in - reverse order, (as opposed to how <c>ERL_DRV_LIST</c> - works), concatenating the strings added to a list. The tail - must be given before <c>ERL_DRV_STRING_CONS</c>.</p> - <p>The <c>ERL_DRV_STRING</c> constructs a string, and ends - it. (So it's the same as <c>ERL_DRV_NIL</c> followed by - <c>ERL_DRV_STRING_CONS</c>.)</p> - <code type="none"><![CDATA[ - /* to send [x, "abc", y] to the port: */ - ErlDrvTermData spec[] = { - ERL_DRV_ATOM, driver_mk_atom("x"), - ERL_DRV_STRING, (ErlDrvTermData)"abc", 3, - ERL_DRV_ATOM, driver_mk_atom("y"), - ERL_DRV_NIL, - ERL_DRV_LIST, 4 - }; - erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); - ]]></code> - <p></p> - <code type="none"><![CDATA[ - /* to send "abc123" to the port: */ - ErlDrvTermData spec[] = { - ERL_DRV_NIL, /* with STRING_CONS, the tail comes first */ - ERL_DRV_STRING_CONS, (ErlDrvTermData)"123", 3, - ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3, - }; - erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); - ]]></code> - <p>The <c>ERL_DRV_EXT2TERM</c> term type is used for passing a - term encoded with the - <seealso marker="erl_ext_dist">external format</seealso>, - i.e., a term that has been encoded by - <seealso marker="erlang#term_to_binary/2">erlang:term_to_binary</seealso>, - <seealso marker="erl_interface:ei">erl_interface</seealso>, etc. - For example, if <c>binp</c> is a pointer to an <c>ErlDrvBinary</c> - that contains the term <c>{17, 4711}</c> encoded with the - <seealso marker="erl_ext_dist">external format</seealso> - and you want to wrap it in a two tuple with the tag <c>my_tag</c>, - i.e., <c>{my_tag, {17, 4711}}</c>, you can do as follows: - </p> - <code type="none"><![CDATA[ - ErlDrvTermData spec[] = { - ERL_DRV_ATOM, driver_mk_atom("my_tag"), - ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size - ERL_DRV_TUPLE, 2, - }; - erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); - ]]></code> - - <p>To build the map <c>#{key1 => 100, key2 => {200, 300}}</c>, the - following call could be made.</p> - <code type="none"><![CDATA[ - ErlDrvPort port = ... - ErlDrvTermData spec[] = { - ERL_DRV_ATOM, driver_mk_atom("key1"), - ERL_DRV_INT, 100, - ERL_DRV_ATOM, driver_mk_atom("key2"), - ERL_DRV_INT, 200, - ERL_DRV_INT, 300, - ERL_DRV_TUPLE, 2, - ERL_DRV_MAP, 2 - }; - erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); - ]]> - </code> - - <p>If you want to pass a binary and don't already have the content - of the binary in an <c>ErlDrvBinary</c>, you can benefit from using - <c>ERL_DRV_BUF2BINARY</c> instead of creating an <c>ErlDrvBinary</c> - via <c>driver_alloc_binary()</c> and then pass the binary via - <c>ERL_DRV_BINARY</c>. The runtime system will often allocate - binaries smarter if <c>ERL_DRV_BUF2BINARY</c> is used. - However, if the content of the binary to pass already resides in - an <c>ErlDrvBinary</c>, it is normally better to pass the binary - using <c>ERL_DRV_BINARY</c> and the <c>ErlDrvBinary</c> in question. - </p> - <p>The <c>ERL_DRV_UINT</c>, <c>ERL_DRV_BUF2BINARY</c>, and - <c>ERL_DRV_EXT2TERM</c> term types were introduced in the 5.6 - version of erts. - </p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> + <marker id="driver_sizeq"></marker> + <p>Returns the number of bytes currently in the driver queue.</p> + <p>This function can be called from any thread if a + <seealso marker="#ErlDrvPDL">port data lock</seealso> + associated with the <c>port</c> is locked by the calling + thread during the call.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n)</nametext></name> - <fsummary>Send term data from driver to port owner</fsummary> + <name><ret>void</ret><nametext>driver_system_info(ErlDrvSysInfo + *sys_info_ptr, size_t size)</nametext></name> + <fsummary>Get information about the Erlang runtime system.</fsummary> <desc> - <marker id="driver_output_term"></marker> - <warning><p><c>driver_output_term()</c> is deprecated and will - be removed in the OTP-R17 release. Use - <seealso marker="#erl_drv_send_term">erl_drv_output_term()</seealso> - instead.</p> - </warning> - <p>The parameters <c>term</c> and <c>n</c> do the same thing - as in <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>.</p> - <p>Note that this function is <em>not</em> thread-safe, not - even when the emulator with SMP support is used.</p> + <marker id="driver_system_info"></marker> + <p>Writes information about the Erlang runtime system into the + <seealso marker="#ErlDrvSysInfo"><c>ErlDrvSysInfo</c></seealso> + structure referred to by the first argument. The second + argument is to be the size of the + <seealso marker="#ErlDrvSysInfo"><c>ErlDrvSysInfo</c></seealso> + structure, that is, <c>sizeof(ErlDrvSysInfo)</c>.</p> + <p>For information about specific fields, see + <seealso marker="#ErlDrvSysInfo"><c>ErlDrvSysInfo</c></seealso>.</p> </desc> </func> + <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_mk_atom(char* string)</nametext></name> - <fsummary>Make an atom from a name</fsummary> + <name><ret>ErlDrvSizeT</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, + char *buf, ErlDrvSizeT len)</nametext></name> + <fsummary>Collect data segments into a buffer.</fsummary> <desc> - <marker id="driver_mk_atom"></marker> - <p>This function returns an atom given a name - <c>string</c>. The atom is created and won't change, so the - return value may be saved and reused, which is faster than - looking up the atom several times.</p> - <p>Note that this function is <em>not</em> thread-safe, not - even when the emulator with SMP support is used.</p> + <marker id="driver_vec_to_buf"></marker> + <p>Collects several segments of data, referenced + by <c>ev</c>, by copying them in order to the buffer + <c>buf</c>, of the size <c>len</c>.</p> + <p>If the data is to be sent from the driver to the port owner + process, it is faster to use + <seealso marker="#driver_outputv"><c>driver_outputv</c></seealso>.</p> + <p>The return value is the space left in the buffer, that is, if + <c>ev</c> contains less than <c>len</c> bytes it is the + difference, and if <c>ev</c> contains <c>len</c> bytes or more, + it is <c>0</c>. This is faster if there is more than one header byte, + as the binary syntax can construct integers directly from + the binary.</p> </desc> </func> + <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_mk_port(ErlDrvPort port)</nametext></name> - <fsummary>Make a erlang term port from a port</fsummary> + <name><ret>void</ret><nametext>erl_drv_busy_msgq_limits(ErlDrvPort port, + ErlDrvSizeT *low, ErlDrvSizeT *high)</nametext></name> + <fsummary>Set and get limits for busy port message queue.</fsummary> <desc> - <marker id="driver_mk_port"></marker> - <p>This function converts a port handle to the erlang term - format, usable in the <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>, and <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> functions.</p> - <p>Note that this function is <em>not</em> thread-safe, not - even when the emulator with SMP support is used.</p> + <marker id="erl_drv_busy_msgq_limits"></marker> + <p>Sets and gets limits that will be used for controlling the + busy state of the port message queue.</p> + <p>The port message queue is set into a busy + state when the amount of command data queued on the + message queue reaches the <c>high</c> limit. The port + message queue is set into a not busy state when the + amount of command data queued on the message queue falls + below the <c>low</c> limit. Command data is in this + context data passed to the port using either + <c>Port ! {Owner, {command, Data}}</c> or + <c>port_command/[2,3]</c>. Notice that these limits + only concerns command data that have not yet reached the + port. The <seealso marker="#set_busy_port">busy port</seealso> + feature can be used for data that has reached the port.</p> + <p>Valid limits are values in the range + <c>[ERL_DRV_BUSY_MSGQ_LIM_MIN, ERL_DRV_BUSY_MSGQ_LIM_MAX]</c>. + Limits are automatically adjusted to be sane. That is, + the system adjusts values so that the low limit used is + lower than or equal to the high limit used. By default the high + limit is 8 kB and the low limit is 4 kB.</p> + <p>By passing a pointer to an integer variable containing + the value <c>ERL_DRV_BUSY_MSGQ_READ_ONLY</c>, the currently used + limit is read and written back to the integer variable. + A new limit can be set by passing a pointer to an integer + variable containing a valid limit. The passed value is + written to the internal limit. The internal limit is then + adjusted. After this the adjusted limit is written + back to the integer variable from which the new value was + read. Values are in bytes.</p> + <p>The busy message queue feature can be disabled either + by setting the <c>ERL_DRV_FLAG_NO_BUSY_MSGQ</c> + <seealso marker="driver_entry#driver_flags">driver flag</seealso> + in the <seealso marker="driver_entry"><c>driver_entry</c></seealso> + used by the driver, or by calling this function with + <c>ERL_DRV_BUSY_MSGQ_DISABLED</c> as a limit (either low or + high). When this feature has been disabled, it cannot be + enabled again. When reading the limits, both are + <c>ERL_DRV_BUSY_MSGQ_DISABLED</c> if this + feature has been disabled.</p> + <p>Processes sending command data to the port are suspended + if either the port is busy or if the port message queue is + busy. Suspended processes are resumed when neither the + port or the port message queue is busy.</p> + <p>For information about busy port functionality, see + <seealso marker="#set_busy_port"><c>set_busy_port</c></seealso>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>erl_drv_send_term(ErlDrvTermData port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> - <fsummary>Send term data to other process than port owner process</fsummary> + <name><ret>void</ret><nametext>erl_drv_cond_broadcast(ErlDrvCond + *cnd)</nametext></name> + <fsummary>Broadcast on a condition variable.</fsummary> <desc> - <marker id="erl_drv_send_term"></marker> - <p>This function is the only way for a driver to send data to - <em>other</em> processes than the port owner process. The - <c>receiver</c> parameter specifies the process to receive - the data.</p> - <note><p>Note that the <c>port</c> parameter is <em>not</em> - an ordinary port handle, but a port handle converted using - <c>driver_mk_port()</c>.</p></note> - <p>The parameters <c>port</c>, <c>term</c> and <c>n</c> do the same thing - as in <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>.</p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> + <marker id="erl_drv_cond_broadcast"></marker> + <p>Broadcasts on a condition variable. That is, if + other threads are waiting on the condition variable being + broadcast on, <em>all</em> of them are woken.</p> + <p><c>cnd</c> is a pointer to a condition variable to broadcast on.</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> - <fsummary>Send term data to other process than port owner process</fsummary> + <name><ret>ErlDrvCond *</ret><nametext>erl_drv_cond_create(char + *name)</nametext></name> + <fsummary>Create a condition variable.</fsummary> <desc> - <marker id="driver_send_term"></marker> - <warning><p><c>driver_send_term()</c> is deprecated and will - be removed in the OTP-R17 release. Use - <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> - instead.</p> - <p>Also note that parameters of <c>driver_send_term()</c> - cannot be properly checked by the runtime system when - executed by arbitrary threads. This may cause the - <c>driver_send_term()</c> function not to fail when - it should.</p> - </warning> - <p>The parameters <c>term</c> and <c>n</c> do the same thing - as in <seealso marker="#erl_drv_output_term">erl_drv_output_term()</seealso>.</p> - <p>This function is only thread-safe when the emulator with SMP - support is used.</p> + <marker id="erl_drv_cond_create"></marker> + <p>Creates a condition variable and returns a pointer to it.</p> + <p><c>name</c> is a string identifying the created condition variable. + It is used to identify the condition variable in planned + future debug functionality.</p> + <p>Returns <c>NULL</c> on failure. The driver + creating the condition variable is responsible for + destroying it before the driver is unloaded.</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>long</ret><nametext>driver_async (ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*))</nametext></name> - <fsummary>Perform an asynchronous call within a driver</fsummary> + <name><ret>void</ret><nametext>erl_drv_cond_destroy(ErlDrvCond + *cnd)</nametext></name> + <fsummary>Destroy a condition variable.</fsummary> <desc> - <marker id="driver_async"></marker> - <p>This function performs an asynchronous call. The function - <c>async_invoke</c> is invoked in a thread separate from the - emulator thread. This enables the driver to perform - time-consuming, blocking operations without blocking the - emulator.</p> - <p>The async thread pool size can be set with the - <seealso marker="erl#async_thread_pool_size">+A</seealso> - command line argument of <seealso marker="erl">erl(1)</seealso>. - If no async thread pool is available, the call is made - synchronously in the thread calling <c>driver_async()</c>. The - current number of async threads in the async thread pool can be - retrieved via - <seealso marker="#driver_system_info">driver_system_info()</seealso>.</p> - <p>If there is a thread pool available, a thread will be - used. If the <c>key</c> argument is null, the threads from the - pool are used in a round-robin way, each call to - <c>driver_async</c> uses the next thread in the pool. With the - <c>key</c> argument set, this behaviour is changed. The two - same values of <c>*key</c> always get the same thread.</p> - <p>To make sure that a driver instance always uses the same - thread, the following call can be used:</p> - <p></p> - <code type="none"><![CDATA[ - unsigned int myKey = driver_async_port_key(myPort); + <marker id="erl_drv_cond_destroy"></marker> + <p>Destroys a condition variable previously created by + <seealso marker="#erl_drv_cond_create"> + <c>erl_drv_cond_create</c></seealso>.</p> + <p><c>cnd</c> is a pointer to a condition variable to destroy.</p> + <p>This function is thread-safe.</p> + </desc> + </func> - r = driver_async(myPort, &myKey, myData, myFunc); - ]]></code> - <p>It is enough to initialize <c>myKey</c> once for each - driver instance.</p> - <p>If a thread is already working, the calls will be - queued up and executed in order. Using the same thread for - each driver instance ensures that the calls will be made in - sequence.</p> - <p>The <c>async_data</c> is the argument to the functions - <c>async_invoke</c> and <c>async_free</c>. It's typically a - pointer to a structure that contains a pipe or event that - can be used to signal that the async operation completed. - The data should be freed in <c>async_free</c>.</p> - <p>When the async operation is done, <seealso marker="driver_entry#ready_async">ready_async</seealso> driver - entry function is called. If <c>ready_async</c> is null in - the driver entry, the <c>async_free</c> function is called - instead.</p> - <p>The return value is -1 if the <c>driver_async</c> call - fails.</p> + <func> + <name><ret>char *</ret><nametext>erl_drv_cond_name(ErlDrvCond + *cnd)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_cnd_name"></marker> + <p>Returns a pointer to the name of the condition.</p> + <p><c>cnd</c> is a pointer to an initialized condition.</p> <note> - <p>As of erts version 5.5.4.3 the default stack size for - threads in the async-thread pool is 16 kilowords, - i.e., 64 kilobyte on 32-bit architectures. - This small default size has been chosen since the - amount of async-threads might be quite large. The - default stack size is enough for drivers delivered - with Erlang/OTP, but might not be sufficiently large - for other dynamically linked in drivers that use the - driver_async() functionality. A suggested stack size - for threads in the async-thread pool can be configured - via the - <seealso marker="erl#async_thread_stack_size">+a</seealso> - command line argument of - <seealso marker="erl">erl(1)</seealso>.</p> + <p>This function is intended for debugging purposes only.</p> </note> </desc> </func> + <func> - <name><ret>unsigned int</ret><nametext>driver_async_port_key (ErlDrvPort port)</nametext></name> - <fsummary>Calculate an async key from an ErlDrvPort</fsummary> + <name><ret>void</ret><nametext>erl_drv_cond_signal(ErlDrvCond + *cnd)</nametext></name> + <fsummary>Signal on a condition variable.</fsummary> <desc> - <marker id="driver_async_port_key"></marker> - <p>This function calculates a key for later use in <seealso - marker="#driver_async">driver_async()</seealso>. The keys are - evenly distributed so that a fair mapping between port id's - and async thread id's is achieved.</p> - <note> - <p>Before OTP-R16, the actual port id could be used as a key - with proper casting, but after the rewrite of the port - subsystem, this is no longer the case. With this function, you - can achieve the same distribution based on port id's as before - OTP-R16.</p> - </note> + <marker id="erl_drv_cond_signal"></marker> + <p>Signals on a condition variable. That is, if + other threads are waiting on the condition variable being + signaled, <em>one</em> of them is woken.</p> + <p><c>cnd</c> is a pointer to a condition variable to signal on.</p> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>driver_lock_driver(ErlDrvPort port)</nametext></name> - <fsummary>Make sure the driver is never unloaded</fsummary> + <name><ret>void</ret><nametext>erl_drv_cond_wait(ErlDrvCond *cnd, + ErlDrvMutex *mtx)</nametext></name> + <fsummary>Wait on a condition variable.</fsummary> <desc> - <marker id="driver_lock_driver"></marker> - <p>This function locks the driver used by the port <c>port</c> - in memory for the rest of the emulator process' - lifetime. After this call, the driver behaves as one of Erlang's - statically linked in drivers.</p> + <marker id="erl_drv_cond_wait"></marker> + <p>Waits on a condition variable. The calling + thread is blocked until another thread wakes it by signaling + or broadcasting on the condition variable. Before the calling + thread is blocked, it unlocks the mutex passed as argument. + When the calling thread is woken, it locks the same mutex before + returning. That is, the mutex currently must be locked by + the calling thread when calling this function.</p> + <p><c>cnd</c> is a pointer to a condition variable to wait on. + <c>mtx</c> is a pointer to a mutex to unlock while waiting.</p> + <note> + <p><c>erl_drv_cond_wait</c> can return even if + no one has signaled or broadcast on the condition + variable. Code calling <c>erl_drv_cond_wait</c> is + always to be prepared for <c>erl_drv_cond_wait</c> + returning even if the condition that the thread was + waiting for has not occurred. That is, when returning from + <c>erl_drv_cond_wait</c>, always check if the condition + has occurred, and if not call <c>erl_drv_cond_wait</c> again.</p> + </note> + <p>This function is thread-safe.</p> </desc> </func> + <func> - <name><ret>ErlDrvPort</ret><nametext>driver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data)</nametext></name> - <fsummary>Create a new port (driver instance)</fsummary> + <name><ret>int</ret><nametext>erl_drv_consume_timeslice(ErlDrvPort port, + int percent)</nametext></name> + <fsummary>Give the runtime system a hint about how much CPU time the + current driver callback call has consumed.</fsummary> <desc> - <p>This function creates a new port executing the same driver - code as the port creating the new port. - A short description of the arguments:</p> + <marker id="erl_drv_consume_timeslice"></marker> + <p>Gives the runtime system a hint about how much CPU time the current + driver callback call has consumed since the last hint, or since the + the start of the callback if no previous hint has been given.</p> <taglist> <tag><c>port</c></tag> - <item>The port handle of the port (driver instance) creating - the new port.</item> - <tag><c>owner_pid</c></tag> - <item>The process id of the Erlang process which will be - owner of the new port. This process will be linked - to the new port. You usually want to use - <c>driver_caller(port)</c> as <c>owner_pid</c>.</item> - <tag><c>name</c></tag> - <item>The port name of the new port. You usually want to - use the same port name as the driver name - (<seealso marker="driver_entry#driver_name">driver_name</seealso> - field of the - <seealso marker="driver_entry">driver_entry</seealso>).</item> - <tag><c>drv_data</c></tag> - <item>The driver defined handle that will be passed in subsequent - calls to driver call-backs. Note, that the - <seealso marker="driver_entry#start">driver start call-back</seealso> - will not be called for this new driver instance. - The driver defined handle is normally created in the - <seealso marker="driver_entry#start">driver start call-back</seealso> - when a port is created via - <seealso marker="erlang#open_port/2">erlang:open_port/2</seealso>. </item> + <item>Port handle of the executing port.</item> + <tag><c>percent</c></tag> + <item>Approximate consumed fraction of a full + time-slice in percent.</item> </taglist> - <p>The caller of <c>driver_create_port()</c> is allowed to - manipulate the newly created port when <c>driver_create_port()</c> - has returned. When - <seealso marker="#smp_support">port level locking</seealso> - is used, the creating port is, however, only allowed to - manipulate the newly created port until the current driver - call-back that was called by the emulator returns.</p> - <note> - <p>When - <seealso marker="#smp_support">port level locking</seealso> - is used, the creating port is only allowed to manipulate - the newly created port until the current driver call-back - returns.</p> - </note> + <p>The time is specified as a fraction, in percent, of a full time-slice + that a port is allowed to execute before it is to surrender the + CPU to other runnable ports or processes. Valid range is + <c>[1, 100]</c>. The scheduling time-slice is not an exact entity, + but can usually be approximated to about 1 millisecond.</p> + <p>Notice that it is up to the runtime system to determine if and + how to use this information. Implementations on some platforms + can use other means to determine the consumed fraction + of the time-slice. Lengthy driver callbacks should, regardless of + this, frequently call this function to determine if it is allowed + to continue execution or not.</p> + <p>This function returns a non-zero value + if the time-slice has been exhausted, and zero if the callback is + allowed to continue execution. If a non-zero value is + returned, the driver callback is to return as soon as possible in + order for the port to be able to yield.</p> + <p>This function is provided to better support co-operative scheduling, + improve system responsiveness, and to make it easier to prevent + misbehaviors of the VM because of a port monopolizing a scheduler + thread. It can be used when dividing lengthy work into some repeated + driver callback calls, without the need to use threads.</p> + <p>See also the important <seealso marker="#WARNING">warning</seealso> + text at the beginning of this manual page.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_thread_create(char *name, - ErlDrvTid *tid, - void * (*func)(void *), - void *arg, - ErlDrvThreadOpts *opts)</nametext></name> - <fsummary>Create a thread</fsummary> + <name><ret>ErlDrvTime</ret><nametext>erl_drv_convert_time_unit(ErlDrvTime + val, ErlDrvTimeUnit from, ErlDrvTimeUnit to)</nametext></name> + <fsummary>Convert time unit of a time value.</fsummary> <desc> - <marker id="erl_drv_thread_create"></marker> - <p>Arguments:</p> + <marker id="erl_drv_convert_time_unit"></marker> + <p>Converts the <c>val</c> value of time unit <c>from</c> to + the corresponding value of time unit <c>to</c>. The result is + rounded using the floor function.</p> <taglist> - <tag><c>name</c></tag> - <item>A string identifying the created thread. It will be used - to identify the thread in planned future debug - functionality. - </item> - <tag><c>tid</c></tag> - <item>A pointer to a thread identifier variable.</item> - <tag><c>func</c></tag> - <item>A pointer to a function to execute in the created thread.</item> - <tag><c>arg</c></tag> - <item>A pointer to argument to the <c>func</c> function.</item> - <tag><c>opts</c></tag> - <item>A pointer to thread options to use or <c>NULL</c>.</item> + <tag><c>val</c></tag> + <item>Value to convert time unit for.</item> + <tag><c>from</c></tag> + <item>Time unit of <c>val</c>.</item> + <tag><c>to</c></tag> + <item>Time unit of returned value.</item> </taglist> - <p>This function creates a new thread. On success <c>0</c> is returned; - otherwise, an <c>errno</c> value is returned to indicate the error. - The newly created thread will begin executing in the function pointed - to by <c>func</c>, and <c>func</c> will be passed <c>arg</c> as - argument. When <c>erl_drv_thread_create()</c> returns the thread - identifier of the newly created thread will be available in - <c>*tid</c>. <c>opts</c> can be either a <c>NULL</c> pointer, or a - pointer to an - <seealso marker="#ErlDrvThreadOpts">ErlDrvThreadOpts</seealso> - structure. If <c>opts</c> is a <c>NULL</c> pointer, default options - will be used; otherwise, the passed options will be used. - </p> - <warning><p>You are not allowed to allocate the - <seealso marker="#ErlDrvThreadOpts">ErlDrvThreadOpts</seealso> - structure by yourself. It has to be allocated and - initialized by - <seealso marker="#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</seealso>. - </p></warning> - <p>The created thread will terminate either when <c>func</c> returns - or if - <seealso marker="#erl_drv_thread_exit">erl_drv_thread_exit()</seealso> - is called by the thread. The exit value of the thread is either - returned from <c>func</c> or passed as argument to - <seealso marker="#erl_drv_thread_exit">erl_drv_thread_exit()</seealso>. - The driver creating the thread has the responsibility of joining the - thread, via - <seealso marker="#erl_drv_thread_join">erl_drv_thread_join()</seealso>, - before the driver is unloaded. It is not possible to create - "detached" threads, i.e., threads that don't need to be joined. - </p> - <warning><p>All created threads need to be joined by the driver before - it is unloaded. If the driver fails to join all threads - created before it is unloaded, the runtime system will - most likely crash when the code of the driver is unloaded. - </p></warning> - <p>This function is thread-safe.</p> + <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid + time unit argument.</p> + <p>See also <seealso marker="#ErlDrvTime"> + <c>ErlDrvTime</c></seealso> and + <seealso marker="#ErlDrvTimeUnit"> + <c>ErlDrvTimeUnit</c></seealso>.</p> </desc> </func> <func> - <name><ret>ErlDrvThreadOpts *</ret><nametext>erl_drv_thread_opts_create(char *name)</nametext></name> - <fsummary>Create thread options</fsummary> + <name><ret>int</ret><nametext>erl_drv_equal_tids(ErlDrvTid tid1, + ErlDrvTid tid2)</nametext></name> + <fsummary>Compare thread identifiers for equality.</fsummary> <desc> - <marker id="erl_drv_thread_opts_create"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>name</c></tag> - <item>A string identifying the created thread options. It will be used - to identify the thread options in planned future debug - functionality. - </item> - </taglist> - <p>This function allocates and initialize a thread option - structure. On failure <c>NULL</c> is returned. A thread option - structure is used for passing options to - <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>. - If the structure isn't modified before it is passed to - <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>, - the default values will be used. - </p> - <warning><p>You are not allowed to allocate the - <seealso marker="#ErlDrvThreadOpts">ErlDrvThreadOpts</seealso> - structure by yourself. It has to be allocated and - initialized by <c>erl_drv_thread_opts_create()</c>. - </p></warning> + <marker id="erl_drv_equal_tids"></marker> + <p>Compares two thread identifiers, <c>tid1</c> and <c>tid2</c>, + for equality.</p> + <p>Returns <c>0</c> it they are not equal, and a value not equal to + <c>0</c> if they are equal.</p> + <note> + <p>A thread identifier can be reused very quickly after + a thread has terminated. Therefore, if a thread + corresponding to one of the involved thread identifiers + has terminated since the thread identifier was saved, + the result of <c>erl_drv_equal_tids</c> does possibly not give + the expected result.</p> + </note> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts)</nametext></name> - <fsummary>Destroy thread options</fsummary> + <name><ret>int</ret><nametext>erl_drv_getenv(const char *key, char + *value, size_t *value_size)</nametext></name> + <fsummary>Get the value of an environment variable.</fsummary> <desc> - <marker id="erl_drv_thread_opts_destroy"></marker> - <p>Arguments:</p> + <marker id="erl_drv_getenv"></marker> + <p>Retrieves the value of an environment variable.</p> <taglist> - <tag><c>opts</c></tag> - <item>A pointer to thread options to destroy.</item> + <tag><c>key</c></tag> + <item>A <c>NULL</c>-terminated string containing the + name of the environment variable.</item> + <tag><c>value</c></tag> + <item>A pointer to an output buffer.</item> + <tag><c>value_size</c></tag> + <item>A pointer to an integer. The integer is used both for + passing input and output sizes (see below).</item> </taglist> - <p>This function destroys thread options previously created by - <seealso marker="#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</seealso>. - </p> + <p>When this function is called, <c>*value_size</c> is to contain the + size of the <c>value</c> buffer.</p> + <p>On success, <c>0</c> is returned, + the value of the environment variable has been written to + the <c>value</c> buffer, and <c>*value_size</c> contains the + string length (excluding the terminating <c>NULL</c> character) of + the value written to the <c>value</c> buffer.</p> + <p>On failure, that is, no such environment variable was found, + a value < <c>0</c> is returned. When the size of the <c>value</c> + buffer is too small, a value > <c>0</c> is returned and + <c>*value_size</c> has been set to the buffer size needed.</p> + <warning> + <p>Do <em>not</em> use libc's <c>getenv</c> or similar C library + interfaces from a driver.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_thread_exit(void *exit_value)</nametext></name> - <fsummary>Terminate calling thread</fsummary> + <name><ret>void</ret><nametext>erl_drv_init_ack(ErlDrvPort port, + ErlDrvData res)</nametext></name> + <fsummary>Acknowledge the start of the port.</fsummary> <desc> - <marker id="erl_drv_thread_exit"></marker> - <p>Arguments:</p> + <marker id="erl_drv_init_ack"></marker> + <p>Acknowledges the start of the port.</p> <taglist> - <tag><c>exit_value</c></tag> - <item>A pointer to an exit value or <c>NULL</c>.</item> + <tag><c>port</c></tag> + <item>The port handle of the port (driver instance) + doing the acknowledgment. + </item> + <tag><c>res</c></tag> + <item>The result of the port initialization. Can be the same + values as the return value of <seealso marker="driver_entry#start"> + <c>start</c></seealso>, that is, any of the error codes or the + <c>ErlDrvData</c> that is to be used for this port. + </item> </taglist> - <p>This function terminates the calling thread with the exit - value passed as argument. You are only allowed to terminate - threads created with - <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>. - The exit value can later be retrieved by another thread via - <seealso marker="#erl_drv_thread_join">erl_drv_thread_join()</seealso>. - </p> + <p>When this function is called the initiating <c>erlang:open_port</c> + call is returned as if the <seealso marker="driver_entry#start"> + <c>start</c></seealso> function had just been called. It can only be + used when flag <seealso marker="driver_entry#driver_flags"> + <c>ERL_DRV_FLAG_USE_INIT_ACK</c></seealso> + has been set on the linked-in driver.</p> + </desc> + </func> + + <func> + <name><ret>ErlDrvTime</ret> + <nametext>erl_drv_monotonic_time(ErlDrvTimeUnit time_unit)</nametext> + </name> + <fsummary>Get Erlang monotonic time.</fsummary> + <desc> + <marker id="erl_drv_monotonic_time"></marker> + <p>Returns <seealso marker="time_correction#Erlang_Monotonic_Time"> + Erlang monotonic time</seealso>. Notice that negative values are + not uncommon.</p> + <p><c>time_unit</c> is time unit of returned value.</p> + <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.</p> + <p>See also <seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso> + and <seealso marker="#ErlDrvTimeUnit"> + <c>ErlDrvTimeUnit</c></seealso>.</p> + </desc> + </func> + + <func> + <name><ret>ErlDrvMutex *</ret><nametext>erl_drv_mutex_create(char + *name)</nametext></name> + <fsummary>Create a mutex.</fsummary> + <desc> + <marker id="erl_drv_mutex_create"></marker> + <p>Creates a mutex and returns a pointer to it.</p> + <p><c>name</c> is a string identifying the created mutex. It is used + to identify the mutex in planned future debug functionality.</p> + <p>Returns <c>NULL</c> on failure. The driver creating the mutex is + responsible for destroying it before the driver is unloaded.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_thread_join(ErlDrvTid tid, void **exit_value)</nametext></name> - <fsummary>Join with another thread</fsummary> + <name><ret>void</ret><nametext>erl_drv_mutex_destroy(ErlDrvMutex + *mtx)</nametext></name> + <fsummary>Destroy a mutex.</fsummary> <desc> - <marker id="erl_drv_thread_join"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>tid</c></tag> - <item>The thread identifier of the thread to join.</item> - <tag><c>exit_value</c></tag> - <item>A pointer to a pointer to an exit value, or <c>NULL</c>.</item> - </taglist> - <p>This function joins the calling thread with another thread, i.e., - the calling thread is blocked until the thread identified by - <c>tid</c> has terminated. On success <c>0</c> is returned; - otherwise, an <c>errno</c> value is returned to indicate the error. - A thread can only be joined once. The behavior of joining - more than once is undefined, an emulator crash is likely. If - <c>exit_value == NULL</c>, the exit value of the terminated thread - will be ignored; otherwise, the exit value of the terminated thread - will be stored at <c>*exit_value</c>. - </p> + <marker id="erl_drv_mutex_destroy"></marker> + <p>Destroys a mutex previously created by + <seealso marker="#erl_drv_mutex_create"> + <c>erl_drv_mutex_create</c></seealso>. + The mutex must be in an unlocked state before it is destroyed.</p> + <p><c>mtx</c> is a pointer to a mutex to destroy.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>ErlDrvTid</ret><nametext>erl_drv_thread_self(void)</nametext></name> - <fsummary>Get the thread identifier of the current thread</fsummary> + <name><ret>void</ret><nametext>erl_drv_mutex_lock(ErlDrvMutex + *mtx)</nametext></name> + <fsummary>Lock a mutex.</fsummary> <desc> - <marker id="erl_drv_thread_self"></marker> - <p>This function returns the thread identifier of the - calling thread. - </p> + <marker id="erl_drv_mutex_lock"></marker> + <p>Locks a mutex. The calling thread is blocked until the mutex has + been locked. A thread that has currently locked the mutex + <em>cannot</em> lock the same mutex again.</p> + <p><c>mtx</c> is a pointer to a mutex to lock.</p> + <warning> + <p>If you leave a mutex locked in an emulator thread + when you let the thread out of your control, you will + <em>very likely</em> deadlock the whole emulator.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_equal_tids(ErlDrvTid tid1, ErlDrvTid tid2)</nametext></name> - <fsummary>Compare thread identifiers for equality</fsummary> + <name><ret>char *</ret><nametext>erl_drv_mutex_name(ErlDrvMutex + *mtx)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> <desc> - <marker id="erl_drv_equal_tids"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>tid1</c></tag> - <item>A thread identifier.</item> - <tag><c>tid2</c></tag> - <item>A thread identifier.</item> - </taglist> - <p>This function compares two thread identifiers for equality, - and returns <c>0</c> it they aren't equal, and - a value not equal to <c>0</c> if they are equal.</p> - <note><p>A Thread identifier may be reused very quickly after - a thread has terminated. Therefore, if a thread - corresponding to one of the involved thread identifiers - has terminated since the thread identifier was saved, - the result of <c>erl_drv_equal_tids()</c> might not give - the expected result. - </p></note> + <marker id="erl_drv_mutex_name"></marker> + <p>Returns a pointer to the mutex name.</p> + <p><c>mtx</c> is a pointer to an initialized mutex.</p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>erl_drv_mutex_trylock(ErlDrvMutex + *mtx)</nametext></name> + <fsummary>Try lock a mutex.</fsummary> + <desc> + <marker id="erl_drv_mutex_trylock"></marker> + <p>Tries to lock a mutex. A thread that has currently locked the mutex + <em>cannot</em> try to lock the same mutex again.</p> + <p><c>mtx</c> is a pointer to a mutex to try to lock.</p> + <p>Returns <c>0</c> on success, otherwise <c>EBUSY</c>.</p> + <warning> + <p>If you leave a mutex locked in an emulator thread + when you let the thread out of your control, you will + <em>very likely</em> deadlock the whole emulator.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>ErlDrvMutex *</ret><nametext>erl_drv_mutex_create(char *name)</nametext></name> - <fsummary>Create a mutex</fsummary> + <name><ret>void</ret><nametext>erl_drv_mutex_unlock(ErlDrvMutex + *mtx)</nametext></name> + <fsummary>Unlock a mutex.</fsummary> <desc> - <marker id="erl_drv_mutex_create"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>name</c></tag> - <item>A string identifying the created mutex. It will be used - to identify the mutex in planned future debug functionality. - </item> - </taglist> - <p>This function creates a mutex and returns a pointer to it. On - failure <c>NULL</c> is returned. The driver creating the mutex - has the responsibility of destroying it before the driver is - unloaded. - </p> + <marker id="erl_drv_mutex_unlock"></marker> + <p>Unlocks a mutex. The mutex currently must be + locked by the calling thread.</p> + <p><c>mtx</c> is a pointer to a mutex to unlock.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_mutex_destroy(ErlDrvMutex *mtx)</nametext></name> - <fsummary>Destroy a mutex</fsummary> + <name><ret>int</ret><nametext>erl_drv_output_term(ErlDrvTermData port, + ErlDrvTermData* term, int n)</nametext></name> + <fsummary>Send term data from driver to port owner.</fsummary> <desc> - <marker id="erl_drv_mutex_destroy"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>mtx</c></tag> - <item>A pointer to a mutex to destroy.</item> - </taglist> - <p>This function destroys a mutex previously created by - <seealso marker="#erl_drv_mutex_create">erl_drv_mutex_create()</seealso>. - The mutex has to be in an unlocked state before being - destroyed. - </p> + <marker id="erl_drv_output_term"></marker> + <p>Sends data in the special driver term + format to the port owner process. This is a fast way to + deliver term data from a driver. It needs no binary + conversion, so the port owner process receives data as + normal Erlang terms. The <seealso marker="#erl_drv_send_term"> + <c>erl_drv_send_term</c></seealso> + functions can be used for sending to any process + on the local node.</p> + <note> + <p>Parameter <c>port</c> is <em>not</em> + an ordinary port handle, but a port handle converted using + <seealso marker="#driver_mk_port"> + <c>driver_mk_port</c></seealso>.</p> + </note> + <p>Parameter <c>term</c> points to an array of + <c>ErlDrvTermData</c> with <c>n</c> elements. This array + contains terms described in the driver term format. Every + term consists of 1-4 elements in the array. The + first term has a term type and then arguments. + Parameter <c>port</c> specifies the sending port.</p> + <p>Tuples, maps, and lists (except strings, see below) + are built in reverse polish notation, so that to build a + tuple, the elements are specified first, and then the tuple + term, with a count. Likewise for lists and maps.</p> + <list type="bulleted"> + <item> + <p>A tuple must be specified with the number of elements. (The + elements precede the <c>ERL_DRV_TUPLE</c> term.)</p> + </item> + <item> + <p>A map must be specified with the number of key-value pairs + <c>N</c>. The key-value pairs must precede the <c>ERL_DRV_MAP</c> + in this order: <c>key1,value1,key2,value2,...,keyN,valueN</c>. + Duplicate keys are not allowed.</p> + </item> + <item> + <p>A list must be specified with the number of elements, + including the tail, which is the last term preceding + <c>ERL_DRV_LIST</c>.</p> + </item> + </list> + <p>The special term <c>ERL_DRV_STRING_CONS</c> is used to + "splice" in a string in a list, a string specified this way is + not a list in itself, but the elements are elements of the + surrounding list.</p> + <pre> +Term type Arguments +--------- --------- +ERL_DRV_NIL +ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string)) +ERL_DRV_INT ErlDrvSInt integer +ERL_DRV_UINT ErlDrvUInt integer +ERL_DRV_INT64 ErlDrvSInt64 *integer_ptr +ERL_DRV_UINT64 ErlDrvUInt64 *integer_ptr +ERL_DRV_PORT ErlDrvTermData port (from driver_mk_port(ErlDrvPort port)) +ERL_DRV_BINARY ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset +ERL_DRV_BUF2BINARY char *buf, ErlDrvUInt len +ERL_DRV_STRING char *str, int len +ERL_DRV_TUPLE int sz +ERL_DRV_LIST int sz +ERL_DRV_PID ErlDrvTermData pid (from driver_connected(ErlDrvPort port) + or driver_caller(ErlDrvPort port)) +ERL_DRV_STRING_CONS char *str, int len +ERL_DRV_FLOAT double *dbl +ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len +ERL_DRV_MAP int sz</pre> + <p>The unsigned integer data type <c>ErlDrvUInt</c> and the + signed integer data type <c>ErlDrvSInt</c> are 64 bits wide + on a 64-bit runtime system and 32 bits wide on a 32-bit + runtime system. They were introduced in ERTS 5.6 + and replaced some of the <c>int</c> arguments in the list above.</p> + <p>The unsigned integer data type <c>ErlDrvUInt64</c> and the + signed integer data type <c>ErlDrvSInt64</c> are always 64 bits + wide. They were introduced in ERTS 5.7.4.</p> + <p>To build the tuple <c>{tcp, Port, [100 | Binary]}</c>, the + following call can be made.</p> + <code type="none"><![CDATA[ +ErlDrvBinary* bin = ... +ErlDrvPort port = ... +ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("tcp"), + ERL_DRV_PORT, driver_mk_port(drvport), + ERL_DRV_INT, 100, + ERL_DRV_BINARY, bin, 50, 0, + ERL_DRV_LIST, 2, + ERL_DRV_TUPLE, 3, +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> + <p>Here <c>bin</c> is a driver binary of length at least 50 and + <c>drvport</c> is a port handle. Notice that <c>ERL_DRV_LIST</c> + comes after the elements of the list, likewise + <c>ERL_DRV_TUPLE</c>.</p> + <p>The <c>ERL_DRV_STRING_CONS</c> term is a way to construct + strings. It works differently from how <c>ERL_DRV_STRING</c> + works. <c>ERL_DRV_STRING_CONS</c> builds a string list in + reverse order (as opposed to how <c>ERL_DRV_LIST</c> + works), concatenating the strings added to a list. The tail + must be specified before <c>ERL_DRV_STRING_CONS</c>.</p> + <p><c>ERL_DRV_STRING</c> constructs a string, and ends + it. (So it is the same as <c>ERL_DRV_NIL</c> followed by + <c>ERL_DRV_STRING_CONS</c>.)</p> + <code type="none"><![CDATA[ +/* to send [x, "abc", y] to the port: */ +ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("x"), + ERL_DRV_STRING, (ErlDrvTermData)"abc", 3, + ERL_DRV_ATOM, driver_mk_atom("y"), + ERL_DRV_NIL, + ERL_DRV_LIST, 4 +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> + <code type="none"><![CDATA[ +/* to send "abc123" to the port: */ +ErlDrvTermData spec[] = { + ERL_DRV_NIL, /* with STRING_CONS, the tail comes first */ + ERL_DRV_STRING_CONS, (ErlDrvTermData)"123", 3, + ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3, +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> + <p>The <c>ERL_DRV_EXT2TERM</c> term type is used for passing a + term encoded with the + <seealso marker="erl_ext_dist">external format</seealso>, + that is, a term that has been encoded by + <seealso marker="erlang#term_to_binary/2"> + <c>erlang:term_to_binary</c></seealso>, + <seealso marker="erl_interface:ei"><c>erl_interface:ei(3)</c></seealso>, + and so on. + For example, if <c>binp</c> is a pointer to an <c>ErlDrvBinary</c> + that contains term <c>{17, 4711}</c> encoded with the + <seealso marker="erl_ext_dist">external format</seealso>, + and you want to wrap it in a two-tuple with the tag <c>my_tag</c>, + that is, <c>{my_tag, {17, 4711}}</c>, you can do as follows:</p> + <code type="none"><![CDATA[ +ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("my_tag"), + ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size + ERL_DRV_TUPLE, 2, +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> + <p>To build the map <c>#{key1 => 100, key2 => {200, 300}}</c>, the + following call can be made.</p> + <code type="none"><![CDATA[ +ErlDrvPort port = ... +ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("key1"), + ERL_DRV_INT, 100, + ERL_DRV_ATOM, driver_mk_atom("key2"), + ERL_DRV_INT, 200, + ERL_DRV_INT, 300, + ERL_DRV_TUPLE, 2, + ERL_DRV_MAP, 2 +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> + <p>If you want to pass a binary and do not already have the content + of the binary in an <c>ErlDrvBinary</c>, you can benefit from using + <c>ERL_DRV_BUF2BINARY</c> instead of creating an <c>ErlDrvBinary</c> + through <seealso marker="#driver_alloc_binary"> + <c>driver_alloc_binary</c></seealso> and then pass the binary through + <c>ERL_DRV_BINARY</c>. The runtime system often allocates + binaries smarter if <c>ERL_DRV_BUF2BINARY</c> is used. + However, if the content of the binary to pass already resides in + an <c>ErlDrvBinary</c>, it is normally better to pass the binary using + <c>ERL_DRV_BINARY</c> and the <c>ErlDrvBinary</c> in question.</p> + <p>The <c>ERL_DRV_UINT</c>, <c>ERL_DRV_BUF2BINARY</c>, and + <c>ERL_DRV_EXT2TERM</c> term types were introduced in + ERTS 5.6.</p> + <p>This function is only thread-safe when the emulator with SMP + support is used.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>erl_drv_putenv(const char *key, char + *value)</nametext></name> + <fsummary>Set the value of an environment variable.</fsummary> + <desc> + <marker id="erl_drv_putenv"></marker> + <p>Sets the value of an environment variable.</p> + <p><c>key</c> is a <c>NULL</c>-terminated string containing the + name of the environment variable.</p> + <p><c>value</c> is a <c>NULL</c>-terminated string containing the + new value of the environment variable.</p> + <p>Returns <c>0</c> on success, otherwise a value <c>!= 0</c>.</p> + <note> + <p>The result of passing the empty string (<c>""</c>) as a value + is platform-dependent. On some platforms the variable value + is set to the empty string, on others the + environment variable is removed.</p> + </note> + <warning> + <p>Do <em>not</em> use libc's <c>putenv</c> or similar C library + interfaces from a driver.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_mutex_lock(ErlDrvMutex *mtx)</nametext></name> - <fsummary>Lock a mutex</fsummary> + <name><ret>ErlDrvRWLock *</ret><nametext>erl_drv_rwlock_create(char + *name)</nametext></name> + <fsummary>Create an rwlock.</fsummary> <desc> - <marker id="erl_drv_mutex_lock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>mtx</c></tag> - <item>A pointer to a mutex to lock.</item> - </taglist> - <p>This function locks a mutex. The calling thread will be - blocked until the mutex has been locked. A thread - which currently has locked the mutex may <em>not</em> lock - the same mutex again. - </p> - <warning><p>If you leave a mutex locked in an emulator thread - when you let the thread out of your control, you will - <em>very likely</em> deadlock the whole emulator. - </p></warning> + <marker id="erl_drv_rwlock_create"></marker> + <p>Creates an rwlock and returns a pointer to it.</p> + <p><c>name</c> is a string identifying the created rwlock. + It is used to identify the rwlock in planned future + debug functionality.</p> + <p>Returns <c>NULL</c> on failure. The driver creating the rwlock + is responsible for destroying it before the driver is unloaded.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_mutex_trylock(ErlDrvMutex *mtx)</nametext></name> - <fsummary>Try lock a mutex</fsummary> + <name><ret>void</ret><nametext>erl_drv_rwlock_destroy(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Destroy an rwlock.</fsummary> <desc> - <marker id="erl_drv_mutex_trylock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>mtx</c></tag> - <item>A pointer to a mutex to try to lock.</item> - </taglist> - <p>This function tries to lock a mutex. If successful <c>0</c>, - is returned; otherwise, <c>EBUSY</c> is returned. A thread - which currently has locked the mutex may <em>not</em> try to - lock the same mutex again. - </p> - <warning><p>If you leave a mutex locked in an emulator thread - when you let the thread out of your control, you will - <em>very likely</em> deadlock the whole emulator. - </p></warning> + <marker id="erl_drv_rwlock_destroy"></marker> + <p>Destroys an rwlock previously created by + <seealso marker="#erl_drv_rwlock_create"> + <c>erl_drv_rwlock_create</c></seealso>. + The rwlock must be in an unlocked state before it is destroyed.</p> + <p><c>rwlck</c> is a pointer to an rwlock to destroy.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_mutex_unlock(ErlDrvMutex *mtx)</nametext></name> - <fsummary>Unlock a mutex</fsummary> + <name><ret>char *</ret><nametext>erl_drv_rwlock_name(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> <desc> - <marker id="erl_drv_mutex_unlock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>mtx</c></tag> - <item>A pointer to a mutex to unlock.</item> - </taglist> - <p>This function unlocks a mutex. The mutex currently has to be - locked by the calling thread. - </p> + <marker id="erl_drv_rwlock_name"></marker> + <p>Returns a pointer to the name of the rwlock.</p> + <p><c>rwlck</c> is a pointer to an initialized rwlock.</p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>void</ret><nametext>erl_drv_rwlock_rlock(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Read lock an rwlock.</fsummary> + <desc> + <marker id="erl_drv_rwlock_rlock"></marker> + <p>Read locks an rwlock. The calling thread is + blocked until the rwlock has been read locked. A thread + that currently has read or read/write locked the rwlock + <em>cannot</em> lock the same rwlock again.</p> + <p><c>rwlck</c> is a pointer to the rwlock to read lock.</p> + <warning> + <p>If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + <em>very likely</em> deadlock the whole emulator.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>ErlDrvCond *</ret><nametext>erl_drv_cond_create(char *name)</nametext></name> - <fsummary>Create a condition variable</fsummary> + <name><ret>void</ret><nametext>erl_drv_rwlock_runlock(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Read unlock an rwlock.</fsummary> <desc> - <marker id="erl_drv_cond_create"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>name</c></tag> - <item>A string identifying the created condition variable. It - will be used to identify the condition variable in planned - future debug functionality. - </item> - </taglist> - <p>This function creates a condition variable and returns a - pointer to it. On failure <c>NULL</c> is returned. The driver - creating the condition variable has the responsibility of - destroying it before the driver is unloaded.</p> + <marker id="erl_drv_rwlock_runlock"></marker> + <p>Read unlocks an rwlock. The rwlock currently must + be read locked by the calling thread.</p> + <p><c>rwlck</c> is a pointer to an rwlock to read unlock.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_destroy(ErlDrvCond *cnd)</nametext></name> - <fsummary>Destroy a condition variable</fsummary> + <name><ret>void</ret><nametext>erl_drv_rwlock_rwlock(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Read/write lock an rwlock.</fsummary> <desc> - <marker id="erl_drv_cond_destroy"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>cnd</c></tag> - <item>A pointer to a condition variable to destroy.</item> - </taglist> - <p>This function destroys a condition variable previously - created by - <seealso marker="#erl_drv_cond_create">erl_drv_cond_create()</seealso>. - </p> - <p>This function is thread-safe.</p> + <marker id="erl_drv_rwlock_rwlock"></marker> + <p>Read/write locks an rwlock. The calling thread + is blocked until the rwlock has been read/write locked. + A thread that currently has read or read/write locked the + rwlock <em>cannot</em> lock the same rwlock again.</p> + <p><c>rwlck</c> is a pointer to an rwlock to read/write lock.</p> + <warning> + <p>If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + <em>very likely</em> deadlock the whole emulator.</p> + </warning> + <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_signal(ErlDrvCond *cnd)</nametext></name> - <fsummary>Signal on a condition variable</fsummary> + <name><ret>void</ret><nametext>erl_drv_rwlock_rwunlock(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Read/write unlock an rwlock.</fsummary> <desc> - <marker id="erl_drv_cond_signal"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>cnd</c></tag> - <item>A pointer to a condition variable to signal on.</item> - </taglist> - <p>This function signals on a condition variable. That is, if - other threads are waiting on the condition variable being - signaled, <em>one</em> of them will be woken. - </p> + <marker id="erl_drv_rwlock_rwunlock"></marker> + <p>Read/write unlocks an rwlock. The rwlock currently must be + read/write locked by the calling thread.</p> + <p><c>rwlck</c> is a pointer to an rwlock to read/write unlock.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_broadcast(ErlDrvCond *cnd)</nametext></name> - <fsummary>Broadcast on a condition variable</fsummary> + <name><ret>int</ret><nametext>erl_drv_rwlock_tryrlock(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Try to read lock an rwlock.</fsummary> <desc> - <marker id="erl_drv_cond_broadcast"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>cnd</c></tag> - <item>A pointer to a condition variable to broadcast on.</item> - </taglist> - <p>This function broadcasts on a condition variable. That is, if - other threads are waiting on the condition variable being - broadcast on, <em>all</em> of them will be woken. - </p> + <marker id="erl_drv_rwlock_tryrlock"></marker> + <p>Tries to read lock an rwlock.</p> + <p><c>rwlck</c> is a pointer to an rwlock to try to read lock.</p> + <p>Returns <c>0</c> on success, otherwise <c>EBUSY</c>. + A thread that currently has read or read/write locked the + rwlock <em>cannot</em> try to lock the same rwlock again.</p> + <warning> + <p>If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + <em>very likely</em> deadlock the whole emulator.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx)</nametext></name> - <fsummary>Wait on a condition variable</fsummary> + <name><ret>int</ret><nametext>erl_drv_rwlock_tryrwlock(ErlDrvRWLock + *rwlck)</nametext></name> + <fsummary>Try to read/write lock an rwlock.</fsummary> <desc> - <marker id="erl_drv_cond_wait"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>cnd</c></tag> - <item>A pointer to a condition variable to wait on.</item> - <tag><c>mtx</c></tag> - <item>A pointer to a mutex to unlock while waiting.</item> - <tag><c></c></tag> - <item></item> - </taglist> - <p>This function waits on a condition variable. The calling - thread is blocked until another thread wakes it by signaling - or broadcasting on the condition variable. Before the calling - thread is blocked it unlocks the mutex passed as argument, and - when the calling thread is woken it locks the same mutex before - returning. That is, the mutex currently has to be locked by - the calling thread when calling this function. - </p> - <note><p><c>erl_drv_cond_wait()</c> might return even though - no-one has signaled or broadcast on the condition - variable. Code calling <c>erl_drv_cond_wait()</c> should - always be prepared for <c>erl_drv_cond_wait()</c> - returning even though the condition that the thread was - waiting for hasn't occurred. That is, when returning from - <c>erl_drv_cond_wait()</c> always check if the condition - has occurred, and if not call <c>erl_drv_cond_wait()</c> - again. - </p></note> + <marker id="erl_drv_rwlock_tryrwlock"></marker> + <p>Tries to read/write lock an rwlock. + A thread that currently has read or read/write locked the + rwlock <em>cannot</em> try to lock the same rwlock again.</p> + <p><c>rwlck</c>is pointer to an rwlock to try to read/write lock.</p> + <p>Returns <c>0</c> on success, otherwise <c>EBUSY</c>.</p> + <warning> + <p>If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + <em>very likely</em> deadlock the whole emulator.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>ErlDrvRWLock *</ret><nametext>erl_drv_rwlock_create(char *name)</nametext></name> - <fsummary>Create an rwlock</fsummary> + <name><ret>int</ret><nametext>erl_drv_send_term(ErlDrvTermData port, + ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> + <fsummary>Send term data to other process than port owner process. + </fsummary> <desc> - <marker id="erl_drv_rwlock_create"></marker> - <p>Arguments:</p> + <marker id="erl_drv_send_term"></marker> + <p>This function is the only way for a driver to send data to + <em>other</em> processes than the port owner process. Parameter + <c>receiver</c> specifies the process to receive the data.</p> + <note> + <p>Parameter <c>port</c> is <em>not</em> an ordinary port handle, but + a port handle converted using + <seealso marker="#driver_mk_port"> + <c>driver_mk_port</c></seealso>.</p> + </note> + <p>Parameters <c>port</c>, <c>term</c>, and <c>n</c> work as in + <seealso marker="#erl_drv_output_term"> + <c>erl_drv_output_term</c></seealso>.</p> + <p>This function is only thread-safe when the emulator with SMP + support is used.</p> + </desc> + </func> + + <func> + <name><ret>void</ret><nametext>erl_drv_set_os_pid(ErlDrvPort port, + ErlDrvSInt pid)</nametext></name> + <fsummary>Set the os_pid for the port.</fsummary> + <desc> + <marker id="erl_drv_set_os_pid"></marker> + <p>Sets the <c>os_pid</c> seen when doing + <seealso marker="erlang:port_info/2"> + <c>erlang:port_info/2</c></seealso> on this port.</p> + <p><c>port</c> is the port handle of the port (driver instance) to set + the pid on. <c>pid</c>is the pid to set.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>erl_drv_thread_create(char *name, ErlDrvTid + *tid, void * (*func)(void *), void *arg, ErlDrvThreadOpts + *opts)</nametext></name> + <fsummary>Create a thread.</fsummary> + <desc> + <marker id="erl_drv_thread_create"></marker> + <p>Creates a new thread.</p> <taglist> <tag><c>name</c></tag> - <item>A string identifying the created rwlock. It will be used to - identify the rwlock in planned future debug functionality. - </item> + <item>A string identifying the created thread. It is used to + identify the thread in planned future debug functionality. + </item> + <tag><c>tid</c></tag> + <item>A pointer to a thread identifier variable.</item> + <tag><c>func</c></tag> + <item>A pointer to a function to execute in the created thread.</item> + <tag><c>arg</c></tag> + <item>A pointer to argument to the <c>func</c> function.</item> + <tag><c>opts</c></tag> + <item>A pointer to thread options to use or <c>NULL</c>.</item> </taglist> - <p>This function creates an rwlock and returns a pointer to it. On - failure <c>NULL</c> is returned. The driver creating the rwlock - has the responsibility of destroying it before the driver is - unloaded. - </p> + <p>Returns <c>0</c> on success, + otherwise an <c>errno</c> value is returned to indicate the error. + The newly created thread begins executing in the function pointed + to by <c>func</c>, and <c>func</c> is passed <c>arg</c> as + argument. When <c>erl_drv_thread_create</c> returns, the thread + identifier of the newly created thread is available in + <c>*tid</c>. <c>opts</c> can be either a <c>NULL</c> pointer, or a + pointer to an + <seealso marker="#ErlDrvThreadOpts"><c>ErlDrvThreadOpts</c></seealso> + structure. If <c>opts</c> is a <c>NULL</c> pointer, default options + are used, otherwise the passed options are used.</p> + <warning> + <p>You are not allowed to allocate the + <seealso marker="#ErlDrvThreadOpts"> + <c>ErlDrvThreadOpts</c></seealso> structure by yourself. + It must be allocated and initialized by + <seealso marker="#erl_drv_thread_opts_create"> + <c>erl_drv_thread_opts_create</c></seealso>.</p> + </warning> + <p>The created thread terminates either when <c>func</c> returns or if + <seealso marker="#erl_drv_thread_exit"> + <c>erl_drv_thread_exit</c></seealso> + is called by the thread. The exit value of the thread is either + returned from <c>func</c> or passed as argument to + <seealso marker="#erl_drv_thread_exit"> + <c>erl_drv_thread_exit</c></seealso>. + The driver creating the thread is responsible for joining the + thread, through <seealso marker="#erl_drv_thread_join"> + <c>erl_drv_thread_join</c></seealso>, + before the driver is unloaded. "Detached" threads cannot be created, + that is, threads that do not need to be joined.</p> + <warning> + <p>All created threads must be joined by the driver before + it is unloaded. If the driver fails to join all threads + created before it is unloaded, the runtime system + most likely crashes when the driver code is unloaded.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_destroy(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Destroy an rwlock</fsummary> + <name><ret>void</ret><nametext>erl_drv_thread_exit(void + *exit_value)</nametext></name> + <fsummary>Terminate calling thread.</fsummary> <desc> - <marker id="erl_drv_rwlock_destroy"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an rwlock to destroy.</item> - </taglist> - <p>This function destroys an rwlock previously created by - <seealso marker="#erl_drv_rwlock_create">erl_drv_rwlock_create()</seealso>. - The rwlock has to be in an unlocked state before being destroyed. - </p> + <marker id="erl_drv_thread_exit"></marker> + <p>Terminates the calling thread with the exit value passed as + argument. <c>exit_value</c> is a pointer to an exit value or + <c>NULL</c>.</p> + <p>You are only allowed to terminate threads created with + <seealso marker="#erl_drv_thread_create"> + <c>erl_drv_thread_create</c></seealso>.</p> + <p>The exit value can later be retrieved by another thread through + <seealso marker="#erl_drv_thread_join"> + <c>erl_drv_thread_join</c></seealso>.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_rlock(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Read lock an rwlock</fsummary> + <name><ret>int</ret><nametext>erl_drv_thread_join(ErlDrvTid tid, void + **exit_value)</nametext></name> + <fsummary>Join with another thread.</fsummary> <desc> - <marker id="erl_drv_rwlock_rlock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an rwlock to read lock.</item> - </taglist> - <p>This function read locks an rwlock. The calling thread will be - blocked until the rwlock has been read locked. A thread - which currently has read or read/write locked the rwlock may - <em>not</em> lock the same rwlock again. - </p> - <warning><p>If you leave an rwlock locked in an emulator thread - when you let the thread out of your control, you will - <em>very likely</em> deadlock the whole emulator. - </p></warning> + <marker id="erl_drv_thread_join"></marker> + <p>Joins the calling thread with another thread, that is, + the calling thread is blocked until the thread identified by + <c>tid</c> has terminated.</p> + <p><c>tid</c> is the thread identifier of the thread to join. + <c>exit_value</c> is a pointer to a pointer to an exit value, + or <c>NULL</c>.</p> + <p>Returns <c>0</c> on success, otherwise an <c>errno</c> + value is returned to indicate the error.</p> + <p>A thread can only be joined once. The behavior of joining + more than once is undefined, an emulator crash is likely. If + <c>exit_value == NULL</c>, the exit value of the terminated thread + is ignored, otherwise the exit value of the terminated thread + is stored at <c>*exit_value</c>.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Try to read lock an rwlock</fsummary> + <name><ret>char *</ret><nametext>erl_drv_thread_name(ErlDrvTid + tid)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> <desc> - <marker id="erl_drv_rwlock_tryrlock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an rwlock to try to read lock.</item> - </taglist> - <p>This function tries to read lock an rwlock. If successful - <c>0</c>, is returned; otherwise, <c>EBUSY</c> is returned. - A thread which currently has read or read/write locked the - rwlock may <em>not</em> try to lock the same rwlock again. - </p> - <warning><p>If you leave an rwlock locked in an emulator thread - when you let the thread out of your control, you will - <em>very likely</em> deadlock the whole emulator. - </p></warning> - <p>This function is thread-safe.</p> + <marker id="erl_drv_rwlock_name"></marker> + <p>Returns a pointer to the name of the thread.</p> + <p><c>tid</c> is a thread identifier.</p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_runlock(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Read unlock an rwlock</fsummary> + <name><ret>ErlDrvThreadOpts *</ret> + <nametext>erl_drv_thread_opts_create(char *name)</nametext></name> + <fsummary>Create thread options.</fsummary> <desc> - <marker id="erl_drv_rwlock_runlock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an rwlock to read unlock.</item> - </taglist> - <p>This function read unlocks an rwlock. The rwlock currently - has to be read locked by the calling thread. - </p> + <marker id="erl_drv_thread_opts_create"></marker> + <p>Allocates and initializes a thread option structure.</p> + <p><c>name</c> is a string identifying the created thread options. + It is used to identify the thread options in planned future debug + functionality.</p> + <p>Returns <c>NULL</c> on failure. A thread option + structure is used for passing options to + <seealso marker="#erl_drv_thread_create"> + <c>erl_drv_thread_create</c></seealso>. + If the structure is not modified before it is passed to + <seealso marker="#erl_drv_thread_create"> + <c>erl_drv_thread_create</c></seealso>, + the default values are used.</p> + <warning> + <p>You are not allowed to allocate the + <seealso marker="#ErlDrvThreadOpts"> + <c>ErlDrvThreadOpts</c></seealso> + structure by yourself. It must be allocated and initialized by + <c>erl_drv_thread_opts_create</c>.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_rwlock(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Read/Write lock an rwlock</fsummary> + <name><ret>void</ret> + <nametext>erl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts)</nametext> + </name> + <fsummary>Destroy thread options.</fsummary> <desc> - <marker id="erl_drv_rwlock_rwlock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an rwlock to read/write lock.</item> - </taglist> - <p>This function read/write locks an rwlock. The calling thread - will be blocked until the rwlock has been read/write locked. - A thread which currently has read or read/write locked the - rwlock may <em>not</em> lock the same rwlock again. - </p> - <warning><p>If you leave an rwlock locked in an emulator thread - when you let the thread out of your control, you will - <em>very likely</em> deadlock the whole emulator. - </p></warning> + <marker id="erl_drv_thread_opts_destroy"></marker> + <p>Destroys thread options previously created by + <seealso marker="#erl_drv_thread_opts_create"> + <c>erl_drv_thread_opts_create</c></seealso>.</p> + <p><c>opts</c> is a pointer to thread options to destroy.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Try to read/write lock an rwlock</fsummary> + <name><ret>ErlDrvTid</ret> + <nametext>erl_drv_thread_self(void)</nametext></name> + <fsummary>Get the thread identifier of the current thread.</fsummary> <desc> - <marker id="erl_drv_rwlock_tryrwlock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an rwlock to try to read/write lock.</item> - </taglist> - <p>This function tries to read/write lock an rwlock. If successful - <c>0</c>, is returned; otherwise, <c>EBUSY</c> is returned. - A thread which currently has read or read/write locked the - rwlock may <em>not</em> try to lock the same rwlock again. - </p> - <warning><p>If you leave an rwlock locked in an emulator thread - when you let the thread out of your control, you will - <em>very likely</em> deadlock the whole emulator. - </p></warning> + <marker id="erl_drv_thread_self"></marker> + <p>Returns the thread identifier of the calling thread.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_rwunlock(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Read/Write unlock an rwlock</fsummary> + <name><ret>ErlDrvTime</ret><nametext>erl_drv_time_offset(ErlDrvTimeUnit + time_unit)</nametext></name> + <fsummary>Get current time offset.</fsummary> + <desc> + <marker id="erl_drv_time_offset"></marker> + <p>Returns the current time offset between + <seealso marker="time_correction#Erlang_Monotonic_Time"> + Erlang monotonic time</seealso> and + <seealso marker="time_correction#Erlang_System_Time"> + Erlang system time</seealso> + converted into the <c>time_unit</c> passed as argument.</p> + <p><c>time_unit</c> is time unit of returned value.</p> + <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.</p> + <p>See also <seealso marker="#ErlDrvTime"> + <c>ErlDrvTime</c></seealso> and + <seealso marker="#ErlDrvTimeUnit"> + <c>ErlDrvTimeUnit</c></seealso>.</p> + </desc> + </func> + + <func> + <name><ret>void *</ret><nametext>erl_drv_tsd_get(ErlDrvTSDKey + key)</nametext></name> + <fsummary>Get thread-specific data.</fsummary> <desc> - <marker id="erl_drv_rwlock_rwunlock"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an rwlock to read/write unlock.</item> - </taglist> - <p>This function read/write unlocks an rwlock. The rwlock - currently has to be read/write locked by the calling thread. - </p> + <marker id="erl_drv_tsd_get"></marker> + <p>Returns the thread-specific data + associated with <c>key</c> for the calling thread.</p> + <p><c>key</c> is a thread-specific data key.</p> + <p>Returns <c>NULL</c> if no data has been associated + with <c>key</c> for the calling thread.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key)</nametext></name> - <fsummary>Create a thread specific data key</fsummary> + <name><ret>int</ret><nametext>erl_drv_tsd_key_create(char *name, + ErlDrvTSDKey *key)</nametext></name> + <fsummary>Create a thread-specific data key.</fsummary> <desc> <marker id="erl_drv_tsd_key_create"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>name</c></tag> - <item>A string identifying the created key. It will be used - to identify the key in planned future debug - functionality. - </item> - <tag><c>key</c></tag> - <item>A pointer to a thread specific data key variable.</item> - </taglist> - <p>This function creates a thread specific data key. On success - <c>0</c> is returned; otherwise, an <c>errno</c> value is returned - to indicate the error. The driver creating the key has the - responsibility of destroying it before the driver is unloaded. - </p> + <p>Creates a thread-specific data key.</p> + <p><c>name</c> is a string identifying the created key. It is used + to identify the key in planned future debug functionality.</p> + <p><c>key</c> is a pointer to a thread-specific data key variable.</p> + <p>Returns <c>0</c> on success, otherwise an <c>errno</c> value is + returned to indicate the error. The driver creating the key is + responsible for destroying it before the driver is unloaded.</p> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_tsd_key_destroy(ErlDrvTSDKey key)</nametext></name> - <fsummary>Destroy a thread specific data key</fsummary> + <name><ret>void</ret><nametext>erl_drv_tsd_key_destroy(ErlDrvTSDKey + key)</nametext></name> + <fsummary>Destroy a thread-specific data key.</fsummary> <desc> <marker id="erl_drv_tsd_key_destroy"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>key</c></tag> - <item>A thread specific data key to destroy.</item> - </taglist> - <p>This function destroys a thread specific data key - previously created by - <seealso marker="#erl_drv_tsd_key_create">erl_drv_tsd_key_create()</seealso>. - All thread specific data using this key in all threads - have to be cleared (see - <seealso marker="#erl_drv_tsd_set">erl_drv_tsd_set()</seealso>) - prior to the call to <c>erl_drv_tsd_key_destroy()</c>. - </p> - <warning><p>A destroyed key is very likely to be reused soon. - Therefore, if you fail to clear the thread specific - data using this key in a thread prior to destroying - the key, you will <em>very likely</em> get unexpected - errors in other parts of the system. - </p></warning> + <p>Destroys a thread-specific data key previously created by + <seealso marker="#erl_drv_tsd_key_create"> + <c>erl_drv_tsd_key_create</c></seealso>. + All thread-specific data using this key in all threads + must be cleared (see <seealso marker="#erl_drv_tsd_set"> + <c>erl_drv_tsd_set</c></seealso>) + before the call to <c>erl_drv_tsd_key_destroy</c>.</p> + <p><c>key</c> is a thread-specific data key to destroy.</p> + <warning> + <p>A destroyed key is very likely to be reused soon. + Therefore, if you fail to clear the thread-specific + data using this key in a thread before destroying + the key, you will <em>very likely</em> get unexpected + errors in other parts of the system.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_tsd_set(ErlDrvTSDKey key, void *data)</nametext></name> - <fsummary>Set thread specific data</fsummary> + <name><ret>void</ret><nametext>erl_drv_tsd_set(ErlDrvTSDKey key, void + *data)</nametext></name> + <fsummary>Set thread-specific data.</fsummary> <desc> <marker id="erl_drv_tsd_set"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>key</c></tag> - <item>A thread specific data key.</item> - <tag><c>data</c></tag> - <item>A pointer to data to associate with <c>key</c> - in calling thread. - </item> - </taglist> - <p>This function sets thread specific data associated with - <c>key</c> for the calling thread. You are only allowed to set - thread specific data for threads while they are fully under your - control. For example, if you set thread specific data in a thread - calling a driver call-back function, it has to be cleared, i.e. - set to <c>NULL</c>, before returning from the driver call-back - function. - </p> - <warning><p>If you fail to clear thread specific data in an - emulator thread before letting it out of your control, - you might not ever be able to clear this data with - later unexpected errors in other parts of the system as - a result. - </p></warning> + <p>Sets thread-specific data associated with + <c>key</c> for the calling thread. You are only allowed to set + thread-specific data for threads while they are fully under your + control. For example, if you set thread-specific data in a thread + calling a driver callback function, it must be cleared, that is, + set to <c>NULL</c>, before returning from the driver callback + function.</p> + <p><c>key</c> is a thread-specific data key.</p> + <p><c>data</c> is a pointer to data to associate with <c>key</c> + in the calling thread.</p> + <warning> + <p>If you fail to clear thread-specific data in an + emulator thread before letting it out of your control, + you might never be able to clear this data with + later unexpected errors in other parts of the system as + a result.</p> + </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void *</ret><nametext>erl_drv_tsd_get(ErlDrvTSDKey key)</nametext></name> - <fsummary>Get thread specific data</fsummary> + <name><ret>char *</ret><nametext>erl_errno_id(int error)</nametext></name> + <fsummary>Get Erlang error atom name from error number.</fsummary> <desc> - <marker id="erl_drv_tsd_get"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>key</c></tag> - <item>A thread specific data key.</item> - </taglist> - <p>This function returns the thread specific data - associated with <c>key</c> for the calling thread. - If no data has been associated with <c>key</c> for - the calling thread, <c>NULL</c> is returned. - </p> - <p>This function is thread-safe.</p> + <marker id="erl_errno_id"></marker> + <p>Returns the atom name of the Erlang error, + given the error number in <c>error</c>. The error atoms are + <c>einval</c>, <c>enoent</c>, and so on. It can be used to make + error terms from the driver.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_putenv(const char *key, char *value)</nametext></name> - <fsummary>Set the value of an environment variable</fsummary> + <name><ret>int</ret><nametext>remove_driver_entry(ErlDrvEntry + *de)</nametext></name> + <fsummary>Remove a driver entry.</fsummary> <desc> - <marker id="erl_drv_putenv"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>key</c></tag> - <item>A null terminated string containing the - name of the environment variable.</item> - <tag><c>value</c></tag> - <item>A null terminated string containing the - new value of the environment variable.</item> - </taglist> - <p>This function sets the value of an environment variable. - It returns <c>0</c> on success, and a value <c>!= 0</c> on - failure. - </p> - <note><p>The result of passing the empty string ("") as a value - is platform dependent. On some platforms the value of the - variable is set to the empty string, on others, the - environment variable is removed.</p> - </note> - <warning><p>Do <em>not</em> use libc's <c>putenv</c> or similar - C library interfaces from a driver. - </p></warning> - <p>This function is thread-safe.</p> + <marker id="remove_driver_entry"></marker> + <p>Removes a driver entry <c>de</c> previously added with + <seealso marker="#add_driver_entry"> + <c>add_driver_entry</c></seealso>.</p> + <p>Driver entries added by the <c>erl_ddll</c> Erlang interface + cannot be removed by using this interface.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>erl_drv_getenv(const char *key, char *value, size_t *value_size)</nametext></name> - <fsummary>Get the value of an environment variable</fsummary> + <name><ret>void</ret><nametext>set_busy_port(ErlDrvPort port, int + on)</nametext></name> + <fsummary>Signal or unsignal port as busy.</fsummary> <desc> - <marker id="erl_drv_getenv"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>key</c></tag> - <item>A null terminated string containing the - name of the environment variable.</item> - <tag><c>value</c></tag> - <item>A pointer to an output buffer.</item> - <tag><c>value_size</c></tag> - <item>A pointer to an integer. The integer is both used for - passing input and output sizes (see below). - </item> - </taglist> - <p>This function retrieves the value of an environment variable. - When called, <c>*value_size</c> should contain the size of - the <c>value</c> buffer. On success <c>0</c> is returned, - the value of the environment variable has been written to - the <c>value</c> buffer, and <c>*value_size</c> contains the - string length (excluding the terminating null character) of - the value written to the <c>value</c> buffer. On failure, - i.e., no such environment variable was found, a value less than - <c>0</c> is returned. When the size of the <c>value</c> - buffer is too small, a value greater than <c>0</c> is returned - and <c>*value_size</c> has been set to the buffer size needed. - </p> - <warning><p>Do <em>not</em> use libc's <c>getenv</c> or similar - C library interfaces from a driver. - </p></warning> - <p>This function is thread-safe.</p> + <marker id="set_busy_port"></marker> + <p>Sets and unsets the busy state of the port. If + <c>on</c> is non-zero, the port is set to busy. If it is zero, + the port is set to not busy. You typically want to combine + this feature with the <seealso marker="#erl_drv_busy_msgq_limits"> + busy port message queue</seealso> functionality.</p> + <p>Processes sending command data to the port are suspended + if either the port or the port message queue + is busy. Suspended processes are resumed when neither the + port or the port message queue is busy. Command data + is in this context data passed to the port using either + <c>Port ! {Owner, {command, Data}}</c> or + <c>port_command/[2,3]</c>.</p> + <p>If the <seealso marker="driver_entry#driver_flags"> + <![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso> has been set in the + <seealso marker="driver_entry"><c>driver_entry</c></seealso>, + data can be forced into the driver through + <seealso marker="erlang#port_command/3"> + <c>erlang:port_command(Port, Data, [force])</c></seealso> + even if the driver has signaled that it is busy.</p> + <p>For information about busy port message queue functionality, see + <seealso marker="#erl_drv_busy_msgq_limits"> + <c>erl_drv_busy_msgq_limits</c></seealso>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>erl_drv_consume_timeslice(ErlDrvPort port, int percent)</nametext></name> - <fsummary>Give the runtime system a hint about how much CPU time the - current driver callback call has consumed</fsummary> + <name><ret>void</ret><nametext>set_port_control_flags(ErlDrvPort port, + int flags)</nametext></name> + <fsummary>Set flags on how to handle control entry function.</fsummary> <desc> - <marker id="erl_drv_consume_timeslice"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>port</c></tag> - <item>Port handle of the executing port.</item> - <tag><c>percent</c></tag> - <item>Approximate consumed fraction of a full - time-slice in percent.</item> - </taglist> - <p>Give the runtime system a hint about how much CPU time the - current driver callback call has consumed since last hint, or - since the start of the callback if no previous hint has been given. - The time is given as a fraction, in percent, of a full time-slice - that a port is allowed to execute before it should surrender the - CPU to other runnable ports or processes. Valid range is - <c>[1, 100]</c>. The scheduling time-slice is not an exact entity, - but can usually be approximated to about 1 millisecond.</p> - - <p>Note that it is up to the runtime system to determine if and - how to use this information. Implementations on some platforms - may use other means in order to determine the consumed fraction - of the time-slice. Lengthy driver callbacks should regardless of - this frequently call the <c>erl_drv_consume_timeslice()</c> - function in order to determine if it is allowed to continue - execution or not.</p> - - <p><c>erl_drv_consume_timeslice()</c> returns a non-zero value - if the time-slice has been exhausted, and zero if the callback is - allowed to continue execution. If a non-zero value is - returned the driver callback should return as soon as possible in - order for the port to be able to yield.</p> - - <p>This function is provided to better support co-operative scheduling, - improve system responsiveness, and to make it easier to prevent - misbehaviors of the VM due to a port monopolizing a scheduler thread. - It can be used when dividing length work into a number of repeated - driver callback calls without the need to use threads. Also see the - important <seealso marker="#WARNING">warning</seealso> text at the - beginning of this document.</p> - </desc> - </func> - - <func> - <name><ret>char *</ret><nametext>erl_drv_cond_name(ErlDrvCond *cnd)</nametext></name> - <fsummary>Get name of driver mutex.</fsummary> - <desc> - <marker id="erl_drv_cnd_name"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>cnd</c></tag> - <item>A pointer to an initialized condition.</item> - </taglist> - <p> - Returns a pointer to the name of the condition. - </p> - <note> - <p>This function is intended for debugging purposes only.</p> - </note> - </desc> - </func> - - <func> - <name><ret>char *</ret><nametext>erl_drv_mutex_name(ErlDrvMutex *mtx)</nametext></name> - <fsummary>Get name of driver mutex.</fsummary> - <desc> - <marker id="erl_drv_mutex_name"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>mtx</c></tag> - <item>A pointer to an initialized mutex.</item> - </taglist> - <p> - Returns a pointer to the name of the mutex. - </p> - <note> - <p>This function is intended for debugging purposes only.</p> - </note> - </desc> - </func> - - <func> - <name><ret>char *</ret><nametext>erl_drv_rwlock_name(ErlDrvRWLock *rwlck)</nametext></name> - <fsummary>Get name of driver mutex.</fsummary> - <desc> - <marker id="erl_drv_rwlock_name"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>rwlck</c></tag> - <item>A pointer to an initialized r/w-lock.</item> - </taglist> - <p> - Returns a pointer to the name of the r/w-lock. - </p> - <note> - <p>This function is intended for debugging purposes only.</p> - </note> - </desc> - </func> - - <func> - <name><ret>char *</ret><nametext>erl_drv_thread_name(ErlDrvTid tid)</nametext></name> - <fsummary>Get name of driver mutex.</fsummary> - <desc> - <marker id="erl_drv_rwlock_name"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>tid</c></tag> - <item>A thread identifier.</item> - </taglist> - <p> - Returns a pointer to the name of the thread. - </p> - <note> - <p>This function is intended for debugging purposes only.</p> - </note> - </desc> - </func> - - <func> - <name><ret>ErlDrvTime</ret><nametext>erl_drv_monotonic_time(ErlDrvTimeUnit time_unit)</nametext></name> - <fsummary>Get Erlang Monotonic Time</fsummary> - <desc> - <marker id="erl_drv_monotonic_time"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>time_unit</c></tag> - <item>Time unit of returned value.</item> - </taglist> - <p> - Returns - <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang - monotonic time</seealso>. Note that it is not uncommon with - negative values. - </p> - <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid - time unit argument, or if called from a thread that is not a - scheduler thread.</p> - <p>See also:</p> - <list> - <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> - <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> - </list> - </desc> - </func> - - <func> - <name><ret>ErlDrvTime</ret><nametext>erl_drv_time_offset(ErlDrvTimeUnit time_unit)</nametext></name> - <fsummary>Get current Time Offset</fsummary> - <desc> - <marker id="erl_drv_time_offset"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>time_unit</c></tag> - <item>Time unit of returned value.</item> - </taglist> - <p>Returns the current time offset between - <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso> - and - <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> - converted into the <c>time_unit</c> passed as argument.</p> - <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid - time unit argument, or if called from a thread that is not a - scheduler thread.</p> - <p>See also:</p> - <list> - <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> - <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> - </list> - </desc> - </func> - - <func> - <name><ret>ErlDrvTime</ret><nametext>erl_drv_convert_time_unit(ErlDrvTime val, ErlDrvTimeUnit from, ErlDrvTimeUnit to)</nametext></name> - <fsummary>Convert time unit of a time value</fsummary> - <desc> - <marker id="erl_drv_convert_time_unit"></marker> - <p>Arguments:</p> - <taglist> - <tag><c>val</c></tag> - <item>Value to convert time unit for.</item> - <tag><c>from</c></tag> - <item>Time unit of <c>val</c>.</item> - <tag><c>to</c></tag> - <item>Time unit of returned value.</item> - </taglist> - <p>Converts the <c>val</c> value of time unit <c>from</c> to - the corresponding value of time unit <c>to</c>. The result is - rounded using the floor function.</p> - <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid - time unit argument.</p> - <p>See also:</p> - <list> - <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> - <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> - </list> - </desc> - </func> - + <marker id="set_port_control_flags"></marker> + <p>Sets flags for how the <seealso marker="driver_entry#control"> + <c>control</c></seealso> driver entry + function will return data to the port owner process. + (The <c>control</c> function is called from + <seealso marker="erlang:port_control/3"> + <c>erlang:port_control/3</c></seealso>.)</p> + <p>Currently there are only two meaningful values for + <c>flags</c>: <c>0</c> means that data is returned in a list, + and <c>PORT_CONTROL_FLAG_BINARY</c> means data is returned as + a binary from <c>control</c>.</p> + </desc> + </func> </funcs> + <section> - <title>SEE ALSO</title> - <p><seealso marker="driver_entry">driver_entry(3)</seealso>, - <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso>, - <seealso marker="erlang">erlang(3)</seealso></p> - <p>An Alternative Distribution Driver (ERTS User's - Guide Ch. 3)</p> + <title>See Also</title> + <p><seealso marker="driver_entry"><c>driver_entry(3)</c></seealso>, + <seealso marker="erlang"><c>erlang(3)</c></seealso>, + <seealso marker="kernel:erl_ddll"><c>erl_ddll(3)</c></seealso>, + section <seealso marker="alt_dist">How to Implement an Alternative + Carrier for the Erlang Distribution></seealso> in the User's Guide</p> </section> </cref> |