diff options
Diffstat (limited to 'erts/doc/src/erl_nif.xml')
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 199 |
1 files changed, 185 insertions, 14 deletions
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 5cbeddabd9..d74ae23a93 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -546,8 +546,8 @@ int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail, <p>Many operations communicating with a process executing a dirty NIF can, however, complete while it executes the dirty NIF. For example, retrieving information about it through - <seealso marker="erlang:process_info/1"> - <c>erlang:process_info</c></seealso>, setting its group leader, + <seealso marker="erlang#process_info/1"> + <c>process_info</c></seealso>, setting its group leader, register/unregister its name, and so on.</p> <p>Termination of a process executing a dirty NIF can only be completed up to a certain point while it executes the dirty NIF. @@ -783,14 +783,16 @@ typedef struct { <p>A process identifier (pid). In contrast to pid terms (instances of <c>ERL_NIF_TERM</c>), <c>ErlNifPid</c>s are self-contained and not bound to any <seealso marker="#ErlNifEnv">environment</seealso>. - <c>ErlNifPid</c> is an opaque type.</p> + <c>ErlNifPid</c> is an opaque type. It can be copied, moved + in memory, forgotten, and so on.</p> </item> <tag><marker id="ErlNifPort"/><c>ErlNifPort</c></tag> <item> <p>A port identifier. In contrast to port ID terms (instances of <c>ERL_NIF_TERM</c>), <c>ErlNifPort</c>s are self-contained and not bound to any <seealso marker="#ErlNifEnv">environment</seealso>. - <c>ErlNifPort</c> is an opaque type.</p> + <c>ErlNifPort</c> is an opaque type. It can be copied, moved + in memory, forgotten, and so on.</p> </item> <tag><marker id="ErlNifResourceType"/><c>ErlNifResourceType</c></tag> <item> @@ -1088,6 +1090,20 @@ typedef struct { </func> <func> + <name since="OTP 22.0"><ret>int</ret> + <nametext>enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2) + </nametext></name> + <fsummary>Compare two pids.</fsummary> + <desc> + <p>Compares two <seealso marker="#ErlNifPid"><c>ErlNifPid</c> + </seealso>s according to term order.</p> + <p>Returns <c>0</c> if <c>pid1</c> and <c>pid2</c> are equal, + < <c>0</c> if <c>pid1</c> < <c>pid2</c>, and + > <c>0</c> if <c>pid1</c> > <c>pid2</c>.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>void</ret> <nametext>enif_cond_broadcast(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> @@ -1392,6 +1408,9 @@ enif_free_iovec(iovec);]]></code> initializes the pid variable <c>*pid</c> from it and returns <c>true</c>. Otherwise returns <c>false</c>. No check is done to see if the process is alive.</p> + <note><p><c>enif_get_local_pid</c> will return false if argument + <c>term</c> is the atom <seealso marker="#enif_make_pid"> + <c>undefined</c></seealso>.</p></note> </desc> </func> @@ -1476,6 +1495,9 @@ enif_free_iovec(iovec);]]></code> <c>term</c>.</p> <p>Returns <c>true</c> on success, or <c>false</c> if <c>term</c> is not a handle to a resource object of type <c>type</c>.</p> + <p><c>enif_get_resource</c> does not add a reference to the resource + object. However, the pointer received in <c>*objp</c> is guaranteed to + be valid at least as long as the resource handle <c>term</c> is valid.</p> </desc> </func> @@ -1871,6 +1893,17 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> + <name since="OTP 22.0"><ret>int</ret> + <nametext>enif_is_pid_undefined(const ErlNifPid* pid)</nametext></name> + <fsummary>Determine if pid is undefined.</fsummary> + <desc> + <p>Returns <c>true</c> if <c>pid</c> has been set as undefined by + <seealso marker="#enif_set_pid_undefined"><c>enif_set_pid_undefined</c> + </seealso>.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>int</ret> <nametext>enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> @@ -2217,6 +2250,18 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </func> <func> + <name since="OTP 22.0"><ret>ERL_NIF_TERM</ret> + <nametext>enif_make_monitor_term(ErlNifEnv* env, const ErlNifMonitor* mon)</nametext></name> + <fsummary>Make monitor term from the given monitor identifier.</fsummary> + <desc> + <p>Creates a term identifying the given monitor received from + <seealso marker="#enif_monitor_process"><c>enif_monitor_process</c> + </seealso>.</p> + <p>This function is primarily intended for debugging purpose.</p> + </desc> + </func> + + <func> <name since="OTP R14B"><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> @@ -2247,7 +2292,8 @@ enif_inspect_iovec(env, max_elements, term, &tail, &iovec); </name> <fsummary>Make a pid term.</fsummary> <desc> - <p>Makes a pid term from <c>*pid</c>.</p> + <p>Makes a pid term or the atom <seealso marker="#enif_set_pid_undefined"> + <c>undefined</c></seealso> from <c>*pid</c>.</p> </desc> </func> @@ -2613,7 +2659,9 @@ enif_map_iterator_destroy(env, &iter);</code> <p>Argument <c>caller_env</c> is the environment of the calling process or callback. Must only be NULL if calling from a custom thread.</p> <p>Returns <c>0</c> on success, < 0 if no <c>down</c> callback is - provided, and > 0 if the process is no longer alive.</p> + provided, and > 0 if the process is no longer alive or if + <c>target_pid</c> is <seealso marker="#enif_set_pid_undefined"> + undefined</seealso>.</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 thread.</p> @@ -2902,6 +2950,10 @@ enif_map_iterator_destroy(env, &iter);</code> References made by <seealso marker="#enif_make_resource"> <c>enif_make_resource</c></seealso> can only be removed by the garbage collector.</p> + <p>There are no guarantees exactly when the destructor of an + unreferenced resource is called. It could be called directly by + <c>enif_release_resource</c> but it could also be scheduled to be + called at a later time possibly by another thread.</p> </desc> </func> @@ -3056,13 +3108,21 @@ 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 triggered, + or <c>ERL_NIF_SELECT_CANCEL</c> which are 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> <p><c>ready_input</c> or <c>ready_output</c> indicates if the event object is ready for reading or writing.</p> - <p>Argument <c>pid</c> may be <c>NULL</c> to indicate the calling process.</p> + <note><p>For complete control over the message format use the newer functions + <seealso marker="#enif_select_read"><c>enif_select_read</c></seealso> or + <seealso marker="#enif_select_write"><c>enif_select_write</c></seealso> + introduced in erts-11.0 (OTP-22.0).</p> + </note> + <p>Argument <c>pid</c> may be <c>NULL</c> to indicate the calling + process. It must not be set as <seealso marker="#enif_set_pid_undefined"> + undefined</seealso>.</p> <p>Argument <c>obj</c> is a resource object obtained from <seealso marker="#enif_alloc_resource"><c>enif_alloc_resource</c></seealso>. The purpose of the resource objects is as a container of the event object @@ -3073,17 +3133,29 @@ enif_map_iterator_destroy(env, &iter);</code> or the atom <c>undefined</c>. It will be passed as <c>Ref</c> in the notifications. If a selective <c>receive</c> statement is used to wait for the notification then a reference created just before the <c>receive</c> will exploit a runtime - optimization that bypasses all earlier received messages in the queue.</p> + optimization that bypasses all earlier received messages in the + queue.</p> <p>The notifications are one-shot only. To receive further notifications of the same type (read or write), repeated calls to <c>enif_select</c> must be made after receiving each notification.</p> + <p><c>ERL_NIF_SELECT_CANCEL</c> can be used to cancel previously + selected events. It must be used in a bitwise OR combination with + <c>ERL_NIF_SELECT_READ</c> and/or <c>ERL_NIF_SELECT_WRITE</c> to + indicate which type of event to cancel. Arguments <c>pid</c> and + <c>ref</c> are ignored when <c>ERL_NIF_SELECT_CANCEL</c> is specified. + The return value will tell if the event was actualy cancelled or if a + notification may already have been sent.</p> <p>Use <c>ERL_NIF_SELECT_STOP</c> as <c>mode</c> in order to safely close an event object that has been passed to <c>enif_select</c>. The <seealso marker="#ErlNifResourceStop"><c>stop</c></seealso> callback of the resource <c>obj</c> will be called when it is safe to close the event object. This safe way of closing event objects must be used - even if all notifications have been received and no further calls to - <c>enif_select</c> have been made.</p> + even if all notifications have been received (or cancelled) and no + further calls to <c>enif_select</c> have been made. + <c>ERL_NIF_SELECT_STOP</c> will first cancel any selected events + before it calls or schedules the <c>stop</c> callback. Arguments + <c>pid</c> and <c>ref</c> are ignored when <c>ERL_NIF_SELECT_STOP</c> + is specified.</p> <p>The first call to <c>enif_select</c> for a specific OS <c>event</c> will establish a relation between the event object and the containing resource. All subsequent calls for an <c>event</c> must pass its containing resource as argument @@ -3105,7 +3177,15 @@ enif_map_iterator_destroy(env, &iter);</code> <item>The stop callback was called directly by <c>enif_select</c>.</item> <tag><c>ERL_NIF_SELECT_STOP_SCHEDULED</c></tag> <item>The stop callback was scheduled to run on some other thread - or later by this thread.</item> + or later by this thread.</item> + <tag><c>ERL_NIF_SELECT_READ_CANCELLED</c></tag> + <item>A read event was cancelled by <c>ERL_NIF_SELECT_CANCEL</c> or + <c>ERL_NIF_SELECT_STOP</c> and is guaranteed not to generate a + <c>ready_input</c> notification message.</item> + <tag><c>ERL_NIF_SELECT_WRITE_CANCELLED</c></tag> + <item>A write event was cancelled by <c>ERL_NIF_SELECT_CANCEL</c> or + <c>ERL_NIF_SELECT_STOP</c> and is guaranteed not to generate a + <c>ready_output</c> notification message.</item> </taglist> <p>Returns a negative value if the call failed where the following bits can be set:</p> <taglist> @@ -3131,6 +3211,43 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { } </code> </note> + <note><p>The mode flag <c>ERL_NIF_SELECT_CANCEL</c> and the return flags + <c>ERL_NIF_SELECT_READ_CANCELLED</c> and + <c>ERL_NIF_SELECT_WRITE_CANCELLED</c> were introduced in erts-11.0 + (OTP-22.0).</p> + </note> + </desc> + </func> + + <func> + <name since="OTP 22.0"><ret>int</ret> + <nametext>enif_select_read(ErlNifEnv* env, ErlNifEvent event, void* obj, + const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)</nametext> + </name> + <name since="OTP 22.0"><ret>int</ret> + <nametext>enif_select_write(ErlNifEnv* env, ErlNifEvent event, void* obj, + const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)</nametext> + </name> + <fsummary>Manage subscription on IO event.</fsummary> + <desc> + <p>These are variants of <seealso marker="#enif_select">enif_select</seealso> + where you can supply your own message term <c>msg</c> that will be sent to + the process instead of the predefined tuple <c>{select,_,_,_}.</c></p> + <p>Argument <c>msg_env</c> must either be <c>NULL</c> or the environment of + <c>msg</c> allocated with <seealso marker="#enif_alloc_env"> + <c>enif_alloc_env</c></seealso>. If argument <c>msg_env</c> is + <c>NULL</c> the term <c>msg</c> will be copied, otherwise both + <c>msg</c> and <c>msg_env</c> will be invalidated by a successful call + to <c>enif_select_read</c> or <c>enif_select_write</c>. The environment + is then to either be freed with <seealso marker="#enif_free_env"> + <c>enif_free_env</c></seealso> or cleared for reuse with + <seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>. An + unsuccessful call will leave <c>msg</c> and <c>msg_env</c> still valid.</p> + <p>Apart from the message format <c>enif_select_read</c> and + <c>enif_select_write</c> behaves exactly the same as <seealso + marker="#enif_select">enif_select</seealso> with argument <c>mode</c> as + either <c>ERL_NIF_SELECT_READ</c> or <c>ERL_NIF_SELECT_WRITE</c>. To + cancel or close events use <seealso marker="#enif_select">enif_select</seealso>.</p> </desc> </func> @@ -3179,8 +3296,9 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { <c>msg</c>) is invalidated by a successful call to <c>enif_send</c>. The environment is to either be freed with <seealso marker="#enif_free_env"> - <c>enif_free_env</c></seealso> of cleared for reuse with - <seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>.</p> + <c>enif_free_env</c></seealso> or cleared for reuse with + <seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>. An + unsuccessful call will leave <c>msg</c> and <c>msg_env</c> still valid.</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 environment is still valid after the call.</p> @@ -3195,6 +3313,17 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { </func> <func> + <name since="OTP 22.0"><ret>void</ret> + <nametext>enif_set_pid_undefined(ErlNifPid* pid)</nametext></name> + <fsummary>Set pid as undefined.</fsummary> + <desc> + <p>Sets an <seealso marker="#ErlNifPid"><c>ErlNifPid</c></seealso> + variable as undefined. See <seealso marker="#enif_is_pid_undefined"> + <c>enif_is_pid_undefined</c></seealso>.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>unsigned</ret> <nametext>enif_sizeof_resource(void* obj)</nametext></name> <fsummary>Get the byte size of a resource object.</fsummary> @@ -3247,6 +3376,48 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { </func> <func> + <name since="OTP 22.0"><ret>ErlNifTermType</ret> + <nametext>enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)</nametext> + </name> + <fsummary>Determine the type of a term.</fsummary> + <desc> + <p>Determines the type of the given term. The term must be an ordinary + Erlang term and not one of the special terms returned by + <seealso marker="#enif_raise_exception"> + <c>enif_raise_exception</c></seealso>, + <seealso marker="#enif_schedule_nif"> + <c>enif_schedule_nif</c></seealso>, or similar.</p> + <p>The following types are defined at the moment:</p> + <taglist> + <tag><c>ERL_NIF_TERM_TYPE_ATOM</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_BITSTRING</c></tag> + <item><p>A bitstring or binary</p></item> + <tag><c>ERL_NIF_TERM_TYPE_FLOAT</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_FUN</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_INTEGER</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_LIST</c></tag> + <item><p>A list, empty or not</p></item> + <tag><c>ERL_NIF_TERM_TYPE_MAP</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_PID</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_PORT</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_REFERENCE</c></tag> + <item/> + <tag><c>ERL_NIF_TERM_TYPE_TUPLE</c></tag> + <item/> + </taglist> + <p>Note that new types may be added in the future, so the caller must + be prepared to handle unknown types.</p> + </desc> + </func> + + <func> <name since="OTP R13B04"><ret>int</ret> <nametext>enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts |