From 4a736966eba5398a22697db6ca67e1e3dd3cd0f2 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 10 Dec 2015 10:58:33 +0100 Subject: erts: Add enif_cpu/now_time and enif_make_unique_integer --- erts/doc/src/erl_nif.xml | 201 ++++++++++++++++++++++++++++++----------------- 1 file changed, 127 insertions(+), 74 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index be0e406b9c..e62f5792a5 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -591,6 +591,21 @@ typedef enum { + ErlNifUniqueInteger + +

An enumeration of the properties that can be requested from + + enif_unique_integer.

+ + ERL_NIF_UNIQUE_POSITIVE +

A positive integer

 + ERL_NIF_UNIQUE_MONOTONIC +

A + strictly + monotonically increasing integer corresponding to creation time

 + + + @@ -689,7 +704,49 @@ typedef enum { a number of repeated NIF-calls without the need to create threads. See also the warning text at the beginning of this document.

+ + + + + ErlNifTimeenif_convert_time_unit(ErlNifTime val, ErlNifTimeUnit from, ErlNifTimeUnit to) + Convert time unit of a time value + + +

Arguments:

+ + val + Value to convert time unit for. + from + Time unit of val. + to + Time unit of returned value. + +

Converts the val value of time unit from to + the corresponding value of time unit to. The result is + rounded using the floor function.

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + + + ERL_NIF_TERMenif_cpu_time(ErlNifEnv *) + + +

Returns the CPU time in the same format as erlang:timestamp(). + The CPU time is the time the current logical cpu has spent executing since + some arbitrary point in the past. + If the OS does not support fetching of this value enif_cpu_time + invokes enif_make_badarg. +

+ + + intenif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)

Same as erl_drv_equal_tids. @@ -1195,6 +1252,24 @@ typedef enum { Create an unsigned integer term

Create an integer term from an unsigned 64-bit integer.

 + + ERL_NIF_TERMenif_make_unique_integer(ErlNifEnv *env, ErlNifUniqueInteger properties) + + +

Returns a unique integer with the same properties as given by erlang:unique_integer/1.

+

env is the environment to create the integer in.

+

+ ERL_NIF_UNIQUE_POSITIVE and ERL_NIF_UNIQUE_MONOTONIC can + be passed as the second argument to change the properties of the + integer returned. It is possible to combine them by or:ing the + two values together. +

+

See also:

+ + ErlNifUniqueInteger + + + ERL_NIF_TERMenif_make_ulong(ErlNifEnv* env, unsigned long i) Create an integer term from an unsigned long int

Create an integer term from an unsigned long int.

 @@ -1265,6 +1340,34 @@ enif_map_iterator_destroy(env, &iter); or false if the iterator is positioned at the head (before the first entry).

 + + + ErlNifTimeenif_monotonic_time(ErlNifTimeUnit time_unit) + Get Erlang Monotonic Time + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

+ Returns + Erlang + monotonic time. Note that it is not uncommon with + negative values. +

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + + ErlNifMutex *enif_mutex_create(char *name)

Same as erl_drv_mutex_create. @@ -1290,6 +1393,11 @@ enif_map_iterator_destroy(env, &iter);

Same as erl_drv_mutex_unlock.

+ ERL_NIF_TERMenif_now_time(ErlNifEnv *env) + +

Retuns an erlang:now() timestamp. + The enif_now_time function is deprecated.

 + ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, const char* module_str, const char* name, ErlNifResourceDtor* dtor, ErlNifResourceFlags flags, ErlNifResourceFlags* tried) @@ -1496,54 +1604,6 @@ enif_map_iterator_destroy(env, &iter);

Same as erl_drv_thread_self.

- intenif_tsd_key_create(char *name, ErlNifTSDKey *key) - -

Same as erl_drv_tsd_key_create. -

- - voidenif_tsd_key_destroy(ErlNifTSDKey key) - -

Same as erl_drv_tsd_key_destroy. -

- - void *enif_tsd_get(ErlNifTSDKey key) - -

Same as erl_drv_tsd_get. -

- - voidenif_tsd_set(ErlNifTSDKey key, void *data) - -

Same as erl_drv_tsd_set. -

- - - - - ErlNifTimeenif_monotonic_time(ErlNifTimeUnit time_unit) - Get Erlang Monotonic Time - - -

Arguments:

- - time_unit - Time unit of returned value. - -

- Returns - Erlang - monotonic time. Note that it is not uncommon with - negative values. -

-

Returns ERL_NIF_TIME_ERROR if called with an invalid - time unit argument, or if called from a thread that is not a - scheduler thread.

-

See also:

- - ErlNifTime - ErlNifTimeUnit - - - ErlNifTimeenif_time_offset(ErlNifTimeUnit time_unit) @@ -1571,33 +1631,26 @@ enif_map_iterator_destroy(env, &iter); - - ErlNifTimeenif_convert_time_unit(ErlNifTime val, ErlNifTimeUnit from, ErlNifTimeUnit to) - Convert time unit of a time value - - -

Arguments:

- - val - Value to convert time unit for. - from - Time unit of val. - to - Time unit of returned value. - -

Converts the val value of time unit from to - the corresponding value of time unit to. The result is - rounded using the floor function.

-

Returns ERL_NIF_TIME_ERROR if called with an invalid - time unit argument.

-

See also:

- - ErlNifTime - ErlNifTimeUnit - - + intenif_tsd_key_create(char *name, ErlNifTSDKey *key) + +

Same as erl_drv_tsd_key_create. +

+ + voidenif_tsd_key_destroy(ErlNifTSDKey key) + +

Same as erl_drv_tsd_key_destroy. +

+ + void *enif_tsd_get(ErlNifTSDKey key) + +

Same as erl_drv_tsd_get. +

+ + voidenif_tsd_set(ErlNifTSDKey key, void *data) + +

Same as erl_drv_tsd_set. +

-
SEE ALSO -- cgit v1.2.3 From 348f3f2ee2d2707e30658c3600e05309ad0e72bf Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 10 Dec 2015 10:59:34 +0100 Subject: erts: Add enif_is_process/port_alive --- erts/doc/src/erl_nif.xml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index e62f5792a5..6befdc124b 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -532,6 +532,14 @@ typedef struct { environment. ErlNifPid is an opaque type.

+ ErlNifPort + +

ErlNifPort is a port identifier. In contrast to + port id terms (instances of ERL_NIF_TERM), ErlNifPort's are self + contained and not bound to any + environment. ErlNifPort + is an opaque type.

+ ErlNifResourceType @@ -801,6 +809,12 @@ typedef enum { pid variable *pid from it and return true. Otherwise return false. No check if the process is alive is done.

+ intenif_get_local_port(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPort* port_id) + Read an local port term +

If term is the port of a node local port, initialize the + port variable *port_id from it and return true. Otherwise return false. + No check if the port is alive is done.

 + intenif_get_list_cell(ErlNifEnv* env, ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail) Get head and tail from a list

Set *head and *tail from @@ -969,6 +983,17 @@ typedef enum { Determine if a term is a port

Return true if term is a port.

 + intenif_is_port_alive(ErlNifEnv* env, ErlNifPort *port_id) + Determine if a local port is alive or not. +

Return true if port_id is currently alive.

+

This function can only be used in a from a NIF-calling thread.

 + + intenif_is_process_alive(ErlNifEnv* env, ErlNifPid *pid) + Determine if a local process is alive or not. +

Return true if pid is currently alive.

+

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.

 + intenif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a reference

Return true if term is a reference.

 -- cgit v1.2.3 From 1bd56e2b5141a3afdca4e854e9b667807bf4e2f3 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 17 Dec 2015 14:14:54 +0100 Subject: erts: Add enif_term_to_binary and enif_binary_to_term --- erts/doc/src/erl_nif.xml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 6befdc124b..47d84bb813 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -655,6 +655,18 @@ typedef enum { have been allocated with enif_alloc_env.

+ intenif_binary_to_term(ErlNifEnv *env, ErlNifBinary *bin, ERL_NIF_TERM *term) + Convert a term from the external format + +

Returns a term that is the result of decoding bin + according to the Erlang external term format.

+

See also:

+ + erlang:binary_to_term/1 + enif_term_to_binary + + + intenif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs) Compare two terms

Return an integer less than, equal to, or greater than @@ -1599,6 +1611,18 @@ enif_map_iterator_destroy(env, &iter);

Same as driver_system_info.

+ intenif_term_to_binary(ErlNifEnv *env, ERL_NIF_TERM term, ErlNifBinary *bin) + Convert a term to the external format + +

Returns a binary data object that is the result of encoding term + according to the Erlang external term format.

+

See also:

+ + erlang:term_to_binary/1 + enif_binary_to_term + + + intenif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts)

Same as erl_drv_thread_create. -- cgit v1.2.3 From 209c5cf22b5cdc70eb48e6afdcddfa7132471aab Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Mon, 1 Feb 2016 11:01:40 +0100 Subject: erts: Add enif_port_command --- erts/doc/src/erl_nif.xml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 47d84bb813..81b6eed24a 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -1464,6 +1464,38 @@ enif_map_iterator_destroy(env, &iter); and upgrade.

 + intenif_port_command(ErlNifEnv* env, const ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg) + Send a port_command to to_port + +

This function works the same as erlang:port_command/2 + except that it is always completely asynchronous. This call may return false + if it detects that the port is already dead, otherwise it will return true. +

+ + env + The environment of the calling process. May not be NULL. + *to_port + The port id of the receiving port. The port id should refer to a + port on the local node. + msg_env + The environment of the message term. Can be a process + independent environment allocated with + enif_alloc_env or NULL. + msg + The message term to send. The same limitations apply as on the + payload to erlang:port_command/2. + +

Using a msg_env of NULL is an optimization which groups together + calls to enif_alloc_env, enif_make_copy, enif_port_command + and enif_free_env into one call. This optimization is only usefull + when a majority of the terms are to be copied from env to the msg_env.

+

The call may return false if it detects that the command failed for some reason. Otherwise true is returned.

+

See also:

+ + enif_get_local_port + + + void *enif_priv_data(ErlNifEnv* env) Get the private data of a NIF library

Return the pointer to the private data that was set by load, -- cgit v1.2.3 From a2a86dadc648dda68b5221a7c1d83b9238be1e25 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Fri, 12 Feb 2016 18:52:20 +0100 Subject: erts: Improve enif_binary_to_term * Accept a raw data buffer instead of ErlNifBinary * Accept option ERL_NIF_BIN2TERM_SAFE * Return number of read bytes --- erts/doc/src/erl_nif.xml | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 81b6eed24a..7a8325c200 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -524,6 +524,18 @@ typedef struct {

Note that ErlNifBinary is a semi-opaque type and you are only allowed to read fields size and data.

 + + ErlNifBinaryToTerm + +

An enumeration of the options that can be given to + enif_binary_to_term. + For default behavior, use the value 0.

+ + ERL_NIF_BIN2TERM_SAFE +

Use this option when receiving data from untrusted sources.

 + + + ErlNifPid

ErlNifPid is a process identifier (pid). In contrast to @@ -655,16 +667,23 @@ typedef enum { have been allocated with enif_alloc_env.

- intenif_binary_to_term(ErlNifEnv *env, ErlNifBinary *bin, ERL_NIF_TERM *term) - Convert a term from the external format + size_tenif_binary_to_term(ErlNifEnv *env, const unsigned char* data, size_t size, ERL_NIF_TERM *term, ErlNifBinaryToTerm opts) + Create a term from the external format -

Returns a term that is the result of decoding bin - according to the Erlang external term format.

-

See also:

- - erlang:binary_to_term/1 - enif_term_to_binary - +

Create a term that is the result of decoding the binary data + at data, which must be encoded according to the Erlang external term format. + No more than size bytes are read from data. Argument opts + correspond to the second argument to + erlang:binary_to_term/2, and must be either 0 or + ERL_NIF_BIN2TERM_SAFE.

+

On success, store the resulting term at *term and return + the actual number of bytes read. Return zero if decoding fails or if opts + is invalid.

+

See also: + ErlNifBinaryToTerm, + erlang:binary_to_term/2 and + enif_term_to_binary. +

intenif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs) -- cgit v1.2.3 From 42a7116dc64892ef4bf7a1483aa9df82d9a34439 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Fri, 12 Feb 2016 18:59:44 +0100 Subject: erts: Polish erl_nif docs --- erts/doc/src/erl_nif.xml | 69 ++++++++++++++++++++++-------------------------- 1 file changed, 32 insertions(+), 37 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 7a8325c200..1e95634d1b 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -614,13 +614,13 @@ typedef enum { ErlNifUniqueInteger

An enumeration of the properties that can be requested from - - enif_unique_integer.

+ enif_unique_integer. + For default properties, use the value 0.

ERL_NIF_UNIQUE_POSITIVE -

A positive integer

 +

Return only positive integers

 ERL_NIF_UNIQUE_MONOTONIC -

A +

Return only strictly monotonically increasing integer corresponding to creation time

 @@ -765,11 +765,10 @@ typedef enum { rounded using the floor function.

Returns ERL_NIF_TIME_ERROR if called with an invalid time unit argument.

-

See also:

- - ErlNifTime - ErlNifTimeUnit - +

See also: + ErlNifTime and + ErlNifTimeUnit. +

@@ -842,7 +841,7 @@ typedef enum { intenif_get_local_port(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPort* port_id) Read an local port term -

If term is the port of a node local port, initialize the +

If term identifies a node local port, initialize the port variable *port_id from it and return true. Otherwise return false. No check if the port is alive is done.

 @@ -1074,7 +1073,7 @@ typedef enum { enif_is_exception, but not to any other NIF API function.

See also: enif_has_pending_exception - and enif_raise_exception + and enif_raise_exception.

In earlier versions (older than erts-7.0, OTP 18) the return value from enif_make_badarg had to be returned from the NIF. This @@ -1320,10 +1319,9 @@ typedef enum { integer returned. It is possible to combine them by or:ing the two values together.

-

See also:

- - ErlNifUniqueInteger - +

See also: + ErlNifUniqueInteger. +

ERL_NIF_TERMenif_make_ulong(ErlNifEnv* env, unsigned long i) @@ -1408,7 +1406,7 @@ enif_map_iterator_destroy(env, &iter); Time unit of returned value.

- Returns + Returns the current Erlang monotonic time. Note that it is not uncommon with negative values. @@ -1416,11 +1414,10 @@ enif_map_iterator_destroy(env, &iter);

Returns ERL_NIF_TIME_ERROR if called with an invalid time unit argument, or if called from a thread that is not a scheduler thread.

-

See also:

- - ErlNifTime - ErlNifTimeUnit - +

See also: + ErlNifTime and + ErlNifTimeUnit. +

@@ -1509,10 +1506,7 @@ enif_map_iterator_destroy(env, &iter); and enif_free_env into one call. This optimization is only usefull when a majority of the terms are to be copied from env to the msg_env.

The call may return false if it detects that the command failed for some reason. Otherwise true is returned.

-

See also:

- - enif_get_local_port - +

See also: enif_get_local_port.

void *enif_priv_data(ErlNifEnv* env) @@ -1649,6 +1643,8 @@ enif_map_iterator_destroy(env, &iter); of cleared for reuse with enif_clear_env.

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.

+

Passing msg_env as NULL is only supported since + erts-8.0 (OTP 19).

 unsignedenif_sizeof_resource(void* obj) @@ -1665,13 +1661,13 @@ enif_map_iterator_destroy(env, &iter); intenif_term_to_binary(ErlNifEnv *env, ERL_NIF_TERM term, ErlNifBinary *bin) Convert a term to the external format -

Returns a binary data object that is the result of encoding term - according to the Erlang external term format.

-

See also:

- - erlang:term_to_binary/1 - enif_binary_to_term - +

Allocates a new binary with enif_alloc_binary + and stores the result of encoding term according to the Erlang external term format.

+

Returns true on success or false if allocation failed.

+

See also: + erlang:term_to_binary/1 and + enif_binary_to_term. +

intenif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts) @@ -1723,11 +1719,10 @@ enif_map_iterator_destroy(env, &iter);

Returns ERL_NIF_TIME_ERROR if called with an invalid time unit argument, or if called from a thread that is not a scheduler thread.

-

See also:

- - ErlNifTime - ErlNifTimeUnit - +

See also: + ErlNifTime and + ErlNifTimeUnit. +

-- cgit v1.2.3