diff options
Diffstat (limited to 'erts/doc/src/erl_nif.xml')
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 53 |
1 files changed, 43 insertions, 10 deletions
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index b9c2e70b57..a3688a250a 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> @@ -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> @@ -1230,6 +1236,17 @@ 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>.</p> + </desc> + </func> + + <func> <name><ret>void</ret><nametext>enif_free(void* ptr)</nametext></name> <fsummary>Free dynamic memory.</fsummary> <desc> @@ -1683,8 +1700,7 @@ enif_inspect_iovec(env, max_elements, term, &tail, &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 +1709,21 @@ enif_inspect_iovec(env, max_elements, term, &tail, &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> @@ -2216,7 +2247,7 @@ enif_inspect_iovec(env, max_elements, term, &tail, &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 @@ -2960,7 +2991,7 @@ enif_map_iterator_destroy(env, &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 +3042,7 @@ enif_map_iterator_destroy(env, &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 +3050,9 @@ enif_map_iterator_destroy(env, &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"> @@ -3086,7 +3117,7 @@ if (retval & 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 @@ -3116,6 +3147,8 @@ if (retval & 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>.</p> </desc> </func> |