aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl_nif.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erl_nif.xml')
-rw-r--r--erts/doc/src/erl_nif.xml146
1 files changed, 130 insertions, 16 deletions
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index ef3cdb89e9..8a9ae58e99 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -367,6 +367,8 @@ return term;</code>
<c>enif_ioq_deq()</c></seealso></item>
<item><seealso marker="#enif_ioq_peek">
<c>enif_ioq_peek()</c></seealso></item>
+ <item><seealso marker="#enif_ioq_peek_head">
+ <c>enif_ioq_peek_head()</c></seealso></item>
<item><seealso marker="#enif_inspect_iovec">
<c>enif_inspect_iovec()</c></seealso></item>
<item><seealso marker="#enif_free_iovec">
@@ -538,7 +540,7 @@ int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
have to wait for a very long time. Blocking multi-scheduling, that
is, calling <seealso marker="erlang#system_flag_multi_scheduling">
<c>erlang:system_flag(multi_scheduling, block)</c></seealso>, can
- also take a very long time to complete. This becaue all ongoing
+ also take a very long time to complete. This is because all ongoing
dirty operations on all dirty schedulers must complete before
the block operation can complete.</p>
<p>Many operations communicating with a process executing a
@@ -588,7 +590,7 @@ int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
<c>unload</c> is called to release the library. All are
described individually below.</p>
<p>The fourth argument <c>NULL</c> is ignored. It
- was earlier used for the deprectated <c>reload</c> callback
+ was earlier used for the deprecated <c>reload</c> callback
which is no longer supported since OTP 20.</p>
<p>If compiling a NIF for static inclusion through
<c>--enable-static-nifs</c>, you must define <c>STATIC_ERLANG_NIF</c>
@@ -807,7 +809,7 @@ typedef void ErlNifResourceDtor(ErlNifEnv* env, void* obj);</code>
<tag><marker id="ErlNifResourceDown"/><c>ErlNifResourceDown</c></tag>
<item>
<code type="none">
-typedef void ErlNifResourceDown(ErlNifEnv* env, void* obj, const ErlNifPid* pid, const ErlNifMonitor* mon);</code>
+typedef void ErlNifResourceDown(ErlNifEnv* env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);</code>
<p>The function prototype of a resource down function,
called on the behalf of <seealso marker="#enif_monitor_process">
enif_monitor_process</seealso>. <c>obj</c> is the resource, <c>pid</c>
@@ -873,7 +875,7 @@ typedef enum {
<item>
<p>An enumeration of the properties that can be requested from
<seealso marker="#enif_make_unique_integer">
- <c>enif_unique_integer</c></seealso>.
+ <c>enif_make_unique_integer</c></seealso>.
For default properties, use value <c>0</c>.</p>
<taglist>
<tag><c>ERL_NIF_UNIQUE_POSITIVE</c></tag>
@@ -972,6 +974,10 @@ typedef struct {
<seealso marker="#enif_make_binary"><c>enif_make_binary</c></seealso>.
An allocated (and owned) <c>ErlNifBinary</c> can be kept between NIF
calls.</p>
+ <p>If you do not need to reallocate or keep the data alive across NIF
+ calls, consider using <seealso marker="#enif_make_new_binary">
+ <c>enif_make_new_binary</c></seealso> instead as it will allocate
+ small binaries on the process heap when possible.</p>
<p>Returns <c>true</c> on success, or <c>false</c> if allocation
fails.</p>
</desc>
@@ -1098,6 +1104,16 @@ typedef struct {
</func>
<func>
+ <name><ret>char*</ret>
+ <nametext>enif_cond_name(ErlNifCond* cnd)</nametext></name>
+ <fsummary></fsummary>
+ <desc>
+ <p>Same as <seealso marker="erl_driver#erl_drv_cond_name">
+ <c>erl_drv_cond_name</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
<name><ret>void</ret>
<nametext>enif_cond_signal(ErlNifCond *cnd)</nametext></name>
<fsummary></fsummary>
@@ -1230,6 +1246,18 @@ typedef struct {
</func>
<func>
+ <name><ret>int</ret><nametext>enif_fprintf(FILE *stream, const char *format, ...)</nametext></name>
+ <fsummary>Format strings and Erlang terms.</fsummary>
+ <desc>
+ <p>Similar to <c>fprintf</c> but this format string also accepts
+ <c>"%T"</c>, which formats Erlang terms.</p>
+ <p>This function was originally intenden for debugging purpose. It is not
+ recommended to print very large terms with <c>%T</c>. The function may
+ change <c>errno</c>, even if successful.</p>
+ </desc>
+ </func>
+
+ <func>
<name><ret>void</ret><nametext>enif_free(void* ptr)</nametext></name>
<fsummary>Free dynamic memory.</fsummary>
<desc>
@@ -1264,7 +1292,7 @@ typedef struct {
ErlNifIOVec *iovec = NULL;
size_t max_elements = 128;
ERL_NIF_TERM tail;
-if (!enif_inspect_iovec(NULL, max_elements, term, &tail, iovec))
+if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec))
return 0;
// Do things with the iovec
@@ -1683,8 +1711,7 @@ enif_inspect_iovec(env, max_elements, term, &amp;tail, &amp;iovec);
<fsummary>Peek inside the IO Queue</fsummary>
<desc>
<p>Get the I/O queue as a pointer to an array of <c>SysIOVec</c>s.
- It also returns the number of elements in <c>iovlen</c>.
- This is the only way to get data out of the queue.</p>
+ It also returns the number of elements in <c>iovlen</c>.</p>
<p>Nothing is removed from the queue by this function, that must be done
with <seealso marker="#enif_ioq_deq"><c>enif_ioq_deq</c></seealso>.</p>
<p>The returned array is suitable to use with the Unix system
@@ -1693,6 +1720,21 @@ enif_inspect_iovec(env, max_elements, term, &amp;tail, &amp;iovec);
</func>
<func>
+ <name><ret>int</ret>
+ <nametext>enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size, ERL_NIF_TERM *bin_term)</nametext></name>
+ <fsummary>Peek the head of the IO Queue.</fsummary>
+ <desc>
+ <p>Get the head of the IO Queue as a binary term.</p>
+ <p>If <c>size</c> is not <c>NULL</c>, the size of the head is placed
+ there.</p>
+ <p>Nothing is removed from the queue by this function, that must be done
+ with <seealso marker="#enif_ioq_deq"><c>enif_ioq_deq</c></seealso>.</p>
+ <p>Returns <c>true</c> on success, or <c>false</c> if the queue is
+ empty.</p>
+ </desc>
+ </func>
+
+ <func>
<name><ret>size_t</ret>
<nametext>enif_ioq_size(ErlNifIOQueue *q)</nametext></name>
<fsummary>Get the current size of the IO Queue</fsummary>
@@ -2143,6 +2185,20 @@ enif_inspect_iovec(env, max_elements, term, &amp;tail, &amp;iovec);
</func>
<func>
+ <name><ret>int</ret>
+ <nametext>enif_make_map_from_arrays(ErlNifEnv* env, ERL_NIF_TERM keys[],
+ ERL_NIF_TERM values[], size_t cnt, ERL_NIF_TERM *map_out)</nametext></name>
+ <fsummary>Make map term from the given keys and values.</fsummary>
+ <desc>
+ <p>Makes a map term from the given keys and values.</p>
+ <p>If successful, this function sets <c>*map_out</c> to the new map and
+ returns <c>true</c>. Returns <c>false</c> there are any duplicate
+ keys.</p>
+ <p>All keys and values must belong to <c>env</c>.</p>
+ </desc>
+ </func>
+
+ <func>
<name><ret>unsigned char *</ret><nametext>enif_make_new_binary(ErlNifEnv*
env, size_t size, ERL_NIF_TERM* termp)</nametext></name>
<fsummary>Allocate and create a new binary term.</fsummary>
@@ -2216,7 +2272,7 @@ enif_inspect_iovec(env, max_elements, term, &amp;tail, &amp;iovec);
<seealso marker="#enif_get_resource"><c>enif_get_resource</c></seealso>.</p>
</item>
<item>
- <p>A resoure term can be serialized with <c>term_to_binary</c> and later
+ <p>A resource term can be serialized with <c>term_to_binary</c> and later
be fully recreated if the resource object is still alive when
<c>binary_to_term</c> is called. A <em>stale</em> resource term will be
returned from <c>binary_to_term</c> if the resource object has
@@ -2596,6 +2652,16 @@ enif_map_iterator_destroy(env, &amp;iter);</code>
</func>
<func>
+ <name><ret>char*</ret>
+ <nametext>enif_mutex_name(ErlNifMutex* mtx)</nametext></name>
+ <fsummary></fsummary>
+ <desc>
+ <p>Same as <seealso marker="erl_driver#erl_drv_mutex_name">
+ <c>erl_drv_mutex_name</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
<name><ret>int</ret>
<nametext>enif_mutex_trylock(ErlNifMutex *mtx)</nametext></name>
<fsummary></fsummary>
@@ -2840,6 +2906,16 @@ enif_map_iterator_destroy(env, &amp;iter);</code>
</func>
<func>
+ <name><ret>char*</ret>
+ <nametext>enif_rwlock_name(ErlNifRWLock* rwlck)</nametext></name>
+ <fsummary></fsummary>
+ <desc>
+ <p>Same as <seealso marker="erl_driver#erl_drv_rwlock_name">
+ <c>erl_drv_rwlock_name</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
<name><ret>void</ret>
<nametext>enif_rwlock_rlock(ErlNifRWLock *rwlck)</nametext></name>
<fsummary></fsummary>
@@ -2960,7 +3036,7 @@ enif_map_iterator_destroy(env, &amp;iter);</code>
<p>Argument <c>mode</c> describes the type of events to wait for. It can be
<c>ERL_NIF_SELECT_READ</c>, <c>ERL_NIF_SELECT_WRITE</c> or a bitwise
OR combination to wait for both. It can also be <c>ERL_NIF_SELECT_STOP</c>
- which is described further below. When a read or write event is triggerred,
+ which is described further below. When a read or write event is triggered,
a notification message like this is sent to the process identified by
<c>pid</c>:</p>
<code type="none">{select, Obj, Ref, ready_input | ready_output}</code>
@@ -3011,7 +3087,7 @@ enif_map_iterator_destroy(env, &amp;iter);</code>
<item>The stop callback was scheduled to run on some other thread
or later by this thread.</item>
</taglist>
- <p>Returns a negative value if the call failed where the follwing bits can be set:</p>
+ <p>Returns a negative value if the call failed where the following bits can be set:</p>
<taglist>
<tag><c>ERL_NIF_SELECT_INVALID_EVENT</c></tag>
<item>Argument <c>event</c> is not a valid OS event object.</item>
@@ -3019,9 +3095,9 @@ enif_map_iterator_destroy(env, &amp;iter);</code>
<item>The system call failed to add the event object to the poll set.</item>
</taglist>
<note>
- <p>Use bitwise AND to test for specific bits in the return vaue.
+ <p>Use bitwise AND to test for specific bits in the return value.
New significant bits may be added in future releases to give more detailed
- information for both failed and successful calls. Do NOT use equallity tests
+ information for both failed and successful calls. Do NOT use equality tests
like <c>==</c>, as that may cause your application to stop working.</p>
<p>Example:</p>
<code type="none">
@@ -3044,9 +3120,10 @@ if (retval &amp; ERL_NIF_SELECT_STOP_CALLED) {
</name>
<fsummary>Get the pid of the calling process.</fsummary>
<desc>
- <p>Initializes the pid variable <c>*pid</c> to represent the
- calling process.</p>
- <p>Returns <c>pid</c>.</p>
+ <p>Initializes the <seealso marker="#ErlNifPid"><c>ErlNifPid</c></seealso>
+ variable at <c>*pid</c> to represent the calling process.</p>
+ <p>Returns <c>pid</c> if successful, or NULL if <c>caller_env</c> is not
+ a <seealso marker="#ErlNifEnv">process-bound environment</seealso>.</p>
</desc>
</func>
@@ -3085,7 +3162,7 @@ if (retval &amp; ERL_NIF_SELECT_STOP_CALLED) {
<c>enif_free_env</c></seealso> of cleared for reuse with
<seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>.</p>
<p>If <c>msg_env</c> is set to <c>NULL</c>, the <c>msg</c> term is
- copied and the original term and its environemt is still valid after
+ copied and the original term and its environment is still valid after
the call.</p>
<p>This function is only thread-safe when the emulator with SMP support
is used. It can only be used in a non-SMP emulator from a NIF-calling
@@ -3115,6 +3192,9 @@ if (retval &amp; ERL_NIF_SELECT_STOP_CALLED) {
<desc>
<p>Similar to <c>snprintf</c> but this format string also accepts
<c>"%T"</c>, which formats Erlang terms.</p>
+ <p>This function was originally intenden for debugging purpose. It is not
+ recommended to print very large terms with <c>%T</c>. The function may
+ change <c>errno</c>, even if successful.</p>
</desc>
</func>
@@ -3178,6 +3258,16 @@ if (retval &amp; ERL_NIF_SELECT_STOP_CALLED) {
</func>
<func>
+ <name><ret>char*</ret>
+ <nametext>enif_thread_name(ErlNifTid tid)</nametext></name>
+ <fsummary>Thread name</fsummary>
+ <desc>
+ <p>Same as <seealso marker="erl_driver#erl_drv_thread_name">
+ <c>erl_drv_thread_name</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
<name><ret>ErlNifThreadOpts *</ret>
<nametext>enif_thread_opts_create(char *name)</nametext></name>
<fsummary></fsummary>
@@ -3295,6 +3385,30 @@ if (retval &amp; ERL_NIF_SELECT_STOP_CALLED) {
<func>
<name><ret>int</ret>
+ <nametext>enif_vfprintf(FILE *stream, const char *format, va_list ap)
+ </nametext></name>
+ <fsummary>Format strings and Erlang terms.</fsummary>
+ <desc>
+ <p>Equivalent to <seealso marker="#enif_fprintf"><c>enif_fprintf</c></seealso>
+ except that its called with a <c>va_list</c> instead of a variable number of
+ arguments.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name><ret>int</ret>
+ <nametext>enif_vsnprintf(char *str, size_t size, const char *format, va_list ap)
+ </nametext></name>
+ <fsummary>Format strings and Erlang terms.</fsummary>
+ <desc>
+ <p>Equivalent to <seealso marker="#enif_snprintf"><c>enif_snprintf</c></seealso>
+ except that its called with a <c>va_list</c> instead of a variable number of
+ arguments.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name><ret>int</ret>
<nametext>enif_whereis_pid(ErlNifEnv *env,
ERL_NIF_TERM name, ErlNifPid *pid)</nametext></name>
<fsummary>Looks up a process by its registered name.</fsummary>