aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl_driver.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erl_driver.xml')
-rw-r--r--erts/doc/src/erl_driver.xml139
1 files changed, 116 insertions, 23 deletions
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index 7c74517b2e..b453a4861e 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -666,7 +666,7 @@ typedef struct ErlDrvBinary {
<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
- most often type casted to a specific pointer in the driver.</p>
+ most often type cast to a specific pointer in the driver.</p>
</item>
<tag>SysIOVec</tag>
<item>
@@ -1014,7 +1014,7 @@ typedef struct ErlIOVec {
<fsummary>Read a system timestamp</fsummary>
<desc>
<marker id="driver_get_now"></marker>
- <p>This function reads a timestamp into the memory pointed to by
+ <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
@@ -1056,7 +1056,7 @@ typedef struct ErlIOVec {
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
+ 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
@@ -1068,7 +1068,7 @@ typedef struct ErlIOVec {
<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>
+ </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>
@@ -1524,7 +1524,7 @@ typedef struct ErlIOVec {
<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
+ <p>Driver entries added by the <c>erl_ddll</c> erlang interface can
not be removed by using this interface.</p>
</desc>
</func>
@@ -1758,7 +1758,7 @@ typedef struct ErlIOVec {
<pre>
Term type Argument(s)
===========================================
-ERL_DRV_NIL
+ERL_DRV_NIL
ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string))
ERL_DRV_INT ErlDrvSInt integer
ERL_DRV_UINT ErlDrvUInt integer
@@ -1779,11 +1779,11 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
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.
+ 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.
+ wide. They were introduced in erts version 5.7.4.
</p>
<p>To build the tuple <c>{tcp, Port, [100 | Binary]}</c>, the
@@ -1879,7 +1879,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<fsummary>Send term data from driver to port owner</fsummary>
<desc>
<marker id="driver_output_term"></marker>
- <warning><p><c>driver_output_term()</c> is deferred and will
+ <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>
@@ -1937,7 +1937,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<fsummary>Send term data to other process than port owner process</fsummary>
<desc>
<marker id="driver_send_term"></marker>
- <warning><p><c>driver_send_term()</c> is deferred and will
+ <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>
@@ -1981,7 +1981,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
thread, the following call can be used:</p>
<p></p>
<code type="none"><![CDATA[
- unsigned int myKey = (unsigned int) myPort;
+ unsigned int myKey = driver_async_port_key(myPort);
r = driver_async(myPort, &myKey, myData, myFunc);
]]></code>
@@ -1998,7 +1998,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
The data should be freed in <c>async_free</c>, because it's
called if <c>driver_async_cancel</c> is called.</p>
<p>When the async operation is done, <seealso marker="driver_entry#ready_async">ready_async</seealso> driver
- entry function is called. If <c>async_ready</c> is null in
+ 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 a handle to the asynchronous task, which
@@ -2022,6 +2022,24 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
</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>
+ <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>
+ </desc>
+ </func>
+ <func>
<name><ret>int</ret><nametext>driver_async_cancel(long id)</nametext></name>
<fsummary>Cancel an asynchronous call</fsummary>
<desc>
@@ -2033,10 +2051,10 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
The user had to implement synchronization of cancellation anyway.
It also unnecessarily complicated the implementation. Therefore,
as of OTP-R15B <c>driver_async_cancel()</c> is deprecated, and
- scheduled for removal in OTP-R16. It will currently always fail,
+ scheduled for removal in OTP-R17. It will currently always fail,
and return 0.</p>
- <warning><p><c>driver_async_cancel()</c> is deferred and will
- be removed in the OTP-R16 release.</p>
+ <warning><p><c>driver_async_cancel()</c> is deprecated and will
+ be removed in the OTP-R17 release.</p>
</warning>
</desc>
@@ -2048,7 +2066,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<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
+ lifetime. After this call, the driver behaves as one of Erlang's
statically linked in drivers.</p>
</desc>
</func>
@@ -2076,7 +2094,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<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
+ 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
@@ -2284,7 +2302,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<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
+ 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
@@ -2469,7 +2487,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
</taglist>
<p>This function broadcasts on a condition variable. That is, if
other threads are waiting on the condition variable being
- broadcasted on, <em>all</em> of them will be woken.
+ broadcast on, <em>all</em> of them will be woken.
</p>
<p>This function is thread-safe.</p>
</desc>
@@ -2498,7 +2516,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
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 broadcasted on the condition
+ 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
@@ -2822,7 +2840,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
<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).
+ passing input and output sizes (see below).
</item>
</taglist>
<p>This function retrieves the value of an environment variable.
@@ -2889,8 +2907,84 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
beginning of this document.</p>
</desc>
</func>
- </funcs>
+ <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>
+
+ </funcs>
<section>
<title>SEE ALSO</title>
<p><seealso marker="driver_entry">driver_entry(3)</seealso>,
@@ -2900,4 +2994,3 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
Guide Ch. 3)</p>
</section>
</cref>
-