diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/erl.xml | 9 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 230 | ||||
| -rw-r--r-- | erts/doc/src/init.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 502 |
4 files changed, 188 insertions, 555 deletions
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 00da503469..f41b6e6149 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -1322,13 +1322,14 @@ <item> <p>Verbose.</p> </item> - <tag><c><![CDATA[+W w | i]]></c></tag> + <tag><c><![CDATA[+W w | i | e]]></c></tag> <item> <p>Sets the mapping of warning messages for <c><![CDATA[error_logger]]></c>. Messages sent to the error logger using one of the warning - routines can be mapped either to errors (default), warnings - (<c><![CDATA[+W w]]></c>), or info reports (<c><![CDATA[+W i]]></c>). The current - mapping can be retrieved using + routines can be mapped either to errors (<c><![CDATA[+W e]]></c>), + warnings (<c><![CDATA[+W w]]></c>), or info reports + (<c><![CDATA[+W i]]></c>). The default is warnings. + The current mapping can be retrieved using <c><![CDATA[error_logger:warning_map/0]]></c>. See <seealso marker="kernel:error_logger#warning_map/0">error_logger(3)</seealso> for further information.</p> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 4bad8b253c..f64381c99d 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -461,8 +461,9 @@ ok independent environment with all its terms is valid until you explicitly invalidates it with <seealso marker="#enif_free_env">enif_free_env</seealso> or <c>enif_send</c>.</p> - <p>All elements of a list/tuple must belong to the same environment as the - list/tuple itself. Terms can be copied between environments with + <p>All contained terms of a list/tuple/map must belong to the same + environment as the list/tuple/map itself. Terms can be copied between + environments with <seealso marker="#enif_make_copy">enif_make_copy</seealso>.</p> </item> <tag><marker id="ErlNifFunc"/>ErlNifFunc</tag> @@ -564,11 +565,11 @@ typedef enum { <funcs> <func><name><ret>void *</ret><nametext>enif_alloc(size_t size)</nametext></name> - <fsummary>Allocate dynamic memory.</fsummary> + <fsummary>Allocate dynamic memory</fsummary> <desc><p>Allocate memory of <c>size</c> bytes. Return NULL if allocation failed.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_alloc_binary(size_t size, ErlNifBinary* bin)</nametext></name> - <fsummary>Create a new binary.</fsummary> + <fsummary>Create a new binary</fsummary> <desc><p>Allocate a new binary of size <c>size</c> bytes. Initialize the structure pointed to by <c>bin</c> to refer to the allocated binary. The binary must either be released by @@ -595,7 +596,7 @@ typedef enum { <desc><p>Allocate a memory managed resource object of type <c>type</c> and size <c>size</c> bytes.</p></desc> </func> <func><name><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext></name> - <fsummary>Clear an environment for reuse.</fsummary> + <fsummary>Clear an environment for reuse</fsummary> <desc><p>Free all terms in an environment and clear it for reuse. The environment must have been allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>. </p></desc> @@ -683,14 +684,14 @@ typedef enum { <c>size-1</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)</nametext></name> - <fsummary>Get the length of atom <c>term</c>.</fsummary> + <fsummary>Get the length of atom <c>term</c></fsummary> <desc><p>Set <c>*len</c> to the length (number of bytes excluding terminating null character) of the atom <c>term</c> with encoding <c>encode</c>. Return true on success or false if <c>term</c> is not an atom.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp)</nametext></name> - <fsummary>Read a floating-point number term.</fsummary> + <fsummary>Read a floating-point number term</fsummary> <desc><p>Set <c>*dp</c> to the floating point value of <c>term</c>. Return true on success or false if <c>term</c> is not a float.</p></desc> </func> @@ -719,17 +720,28 @@ typedef enum { non-empty list.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len)</nametext></name> - <fsummary>Get the length of list <c>term</c>.</fsummary> + <fsummary>Get the length of list <c>term</c></fsummary> <desc><p>Set <c>*len</c> to the length of list <c>term</c> and return true, or return false if <c>term</c> is not a list.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip)</nametext></name> - <fsummary>Read an long integer term.</fsummary> + <fsummary>Read an long integer term</fsummary> <desc><p>Set <c>*ip</c> to the long integer value of <c>term</c> and return true, or return false if <c>term</c> is not an integer or is outside the bounds of type <c>long int</c>.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name> + <func><name><ret>int</ret><nametext>enif_get_map_size(ErlNifEnv* env, ERL_NIF_TERM term, size_t *size)</nametext></name> + <fsummary>Read the size of a map term</fsummary> + <desc><p>Set <c>*size</c> to the number of key-value pairs in the map <c>term</c> and + return true, or return false if <c>term</c> is not a map.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_map_value(ErlNifEnv* env, ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)</nametext></name> + <fsummary>Get the value of a key in a map</fsummary> + <desc><p>Set <c>*value</c> to the value associated with <c>key</c> in the + map <c>map</c> and return true. Return false if <c>map</c> is not a map + or if <c>map</c> does not contain <c>key</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name> <fsummary>Get the pointer to a resource object</fsummary> <desc><p>Set <c>*objp</c> to point to the resource object referred to by <c>term</c>.</p> <p>Return true on success or false if <c>term</c> is not a handle to a resource object @@ -738,7 +750,7 @@ typedef enum { <func><name><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env, ERL_NIF_TERM list, char* buf, unsigned size, ErlNifCharEncoding encode)</nametext></name> - <fsummary>Get a C-string from a list.</fsummary> + <fsummary>Get a C-string from a list</fsummary> <desc><p>Write a null-terminated string, in the buffer pointed to by <c>buf</c> with size <c>size</c>, consisting of the characters in the string <c>list</c>. The characters are written using encoding @@ -751,7 +763,7 @@ typedef enum { <c>size</c> is less than 1.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array)</nametext></name> - <fsummary>Inspect the elements of a tuple.</fsummary> + <fsummary>Inspect the elements of a tuple</fsummary> <desc><p>If <c>term</c> is a tuple, set <c>*array</c> to point to an array containing the elements of the tuple and set <c>*arity</c> to the number of elements. Note that the array @@ -761,28 +773,35 @@ typedef enum { tuple.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip)</nametext></name> - <fsummary>Read an unsigned integer term.</fsummary> + <fsummary>Read an unsigned integer term</fsummary> <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of type <c>unsigned int</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip)</nametext></name> - <fsummary>Read an unsigned 64-bit integer term.</fsummary> + <fsummary>Read an unsigned 64-bit integer term</fsummary> <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of an unsigned 64-bit integer.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name> - <fsummary>Read an unsigned integer term.</fsummary> + <fsummary>Read an unsigned integer term</fsummary> <desc><p>Set <c>*ip</c> to the unsigned long integer value of <c>term</c> and return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of type <c>unsigned long</c>.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env)</nametext></name> - <fsummary>Check if an exception has been raised.</fsummary> + <func><name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env, ERL_NIF_TERM* reason)</nametext></name> + <fsummary>Check if an exception has been raised</fsummary> <desc><p>Return true if a pending exception is associated - with the environment <c>env</c>. The only possible exception is currently - <c>badarg</c> (see <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>).</p></desc> + with the environment <c>env</c>. If <c>reason</c> is a null pointer, ignore it. + Otherwise, if there's a pending exception associated with <c>env</c>, set the ERL_NIF_TERM + to which <c>reason</c> points to the value of the exception's term. For example, if + <seealso marker="#enif_make_badarg">enif_make_badarg</seealso> is called to set a + pending <c>badarg</c> exception, a subsequent call to <c>enif_has_pending_exception(env, &reason)</c> + will set <c>reason</c> to the atom <c>badarg</c>, then return true.</p> + <p>See also: <seealso marker="#enif_make_badarg">enif_make_badarg</seealso> + and <seealso marker="#enif_raise_exception">enif_raise_exception</seealso>.</p> + </desc> </func> <func><name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name> <fsummary>Inspect the content of a binary</fsummary> @@ -817,6 +836,10 @@ typedef enum { <fsummary>Determine if a term is an exception</fsummary> <desc><p>Return true if <c>term</c> is an exception.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_is_map(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> + <fsummary>Determine if a term is a map</fsummary> + <desc><p>Return true if <c>term</c> is a map, false otherwise.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_is_number(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is a number (integer or float)</fsummary> <desc><p>Return true if <c>term</c> is a number.</p></desc> @@ -890,18 +913,19 @@ typedef enum { </p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name> - <fsummary>Make a badarg exception.</fsummary> + <fsummary>Make a badarg exception</fsummary> <desc><p>Make a badarg exception to be returned from a NIF, and associate it with the environment <c>env</c>. Once a NIF or any function it calls invokes <c>enif_make_badarg</c>, the runtime ensures that a <c>badarg</c> exception is raised when the NIF returns, even if the NIF attempts to return a non-exception term instead. - The return value from <c>enif_make_badarg</c> may only be used as - return value from the NIF that invoked it (direct or indirectly) + The return value from <c>enif_make_badarg</c> may be used only as the + return value from the NIF that invoked it (directly or indirectly) or be passed to <seealso marker="#enif_is_exception">enif_is_exception</seealso>, but not to any other NIF API function.</p> - <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso>. + <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso> + and <seealso marker="#enif_raise_exception">enif_raise_exception</seealso> </p> <note><p>In earlier versions (older than erts-7.0, OTP 18) the return value from <c>enif_make_badarg</c> had to be returned from the NIF. This @@ -909,14 +933,14 @@ typedef enum { if <c>enif_make_badarg</c> has been invoked.</p></note></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name> - <fsummary>Make a binary term.</fsummary> + <fsummary>Make a binary term</fsummary> <desc><p>Make a binary term from <c>bin</c>. Any ownership of the binary data will be transferred to the created term and <c>bin</c> should be considered read-only for the rest of the NIF call and then as released.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term)</nametext></name> - <fsummary>Make a copy of a term.</fsummary> + <fsummary>Make a copy of a term</fsummary> <desc><p>Make a copy of term <c>src_term</c>. The copy will be created in environment <c>dst_env</c>. The source term may be located in any environment.</p></desc> @@ -957,7 +981,7 @@ typedef enum { <desc><p>Create an integer term from a signed 64-bit integer.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext></name> - <fsummary>Create a list term.</fsummary> + <fsummary>Create a list term</fsummary> <desc><p>Create an ordinary list term of length <c>cnt</c>. Expects <c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the elements of the list. An empty list is returned if <c>cnt</c> is 0.</p></desc> @@ -971,28 +995,21 @@ typedef enum { <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name> - <fsummary>Create a list term.</fsummary> + <fsummary>Create a list term</fsummary> <desc><p>Create an ordinary list term with length indicated by the function name. Prefer these functions (macros) over the variadic <c>enif_make_list</c> to get a compile time error if the number of arguments does not match.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail)</nametext></name> - <fsummary>Create a list cell.</fsummary> + <fsummary>Create a list cell</fsummary> <desc><p>Create a list cell <c>[head | tail]</c>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name> - <fsummary>Create a list term from an array.</fsummary> + <fsummary>Create a list term from an array</fsummary> <desc><p>Create an ordinary list containing the elements of array <c>arr</c> of length <c>cnt</c>. An empty list is returned if <c>cnt</c> is 0.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM term, ERL_NIF_TERM *list)</nametext></name> - <fsummary>Create the reverse list of the list <c>term</c>.</fsummary> - <desc><p>Set <c>*list</c> to the reverse list of the list <c>term</c> and return true, - or return false if <c>term</c> is not a list. This function should only be used on - short lists as a copy will be created of the list which will not be released until after the - nif returns.</p></desc> - </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_long(ErlNifEnv* env, long int i)</nametext></name> <fsummary>Create an integer term from a long int</fsummary> <desc><p>Create an integer term from a <c>long int</c>.</p></desc> @@ -1007,12 +1024,42 @@ typedef enum { reallocated.</p><p>Return a pointer to the raw binary data and set <c>*termp</c> to the binary term.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_new_map(ErlNifEnv* env)</nametext></name> + <fsummary>Make an empty map term</fsummary> + <desc><p>Make an empty map term.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_make_map_put(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value, ERL_NIF_TERM* map_out)</nametext></name> + <fsummary>Insert key-value pair in map</fsummary> + <desc><p>Make a copy of map <c>map_in</c> and insert <c>key</c> with + <c>value</c>. If <c>key</c> already exists in <c>map_in</c>, the old + associated value is replaced by <c>value</c>. If successful set + <c>*map_out</c> to the new map and return true. Return false if + <c>map_in</c> is not a map.</p> + <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_make_map_update(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value, ERL_NIF_TERM* map_out)</nametext></name> + <fsummary>Replace value for key in map</fsummary> + <desc><p>Make a copy of map <c>map_in</c> and replace the old associated + value for <c>key</c> with <c>new_value</c>. If successful set + <c>*map_out</c> to the new map and return true. Return false if + <c>map_in</c> is not a map or if it does no contain <c>key</c>.</p> + <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_make_map_remove(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)</nametext></name> + <fsummary>Remove key from map</fsummary> + <desc><p>If map <c>map_in</c> contains <c>key</c>, make a copy of + <c>map_in</c> in <c>*map_out</c> and remove <c>key</c> and associated + value. If map <c>map_in</c> does not contain <c>key</c>, set + <c>*map_out</c> to <c>map_in</c>. Return true for success or false if + <c>map_in</c> is not a map.</p> + <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)</nametext></name> <fsummary>Make a pid term</fsummary> <desc><p>Make a pid term from <c>*pid</c>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ref(ErlNifEnv* env)</nametext></name> - <fsummary>Create a reference.</fsummary> + <fsummary>Create a reference</fsummary> <desc><p>Create a reference like <seealso marker="erlang#make_ref-0">erlang:make_ref/0</seealso>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_resource(ErlNifEnv* env, void* obj)</nametext></name> @@ -1050,20 +1097,28 @@ typedef enum { <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p> </desc> </func> + <func><name><ret>int</ret><nametext>enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out)</nametext></name> + <fsummary>Create the reverse of a list</fsummary> + <desc><p>Set <c>*list_out</c> to the reverse list of the list <c>list_in</c> and return true, + or return false if <c>list_in</c> is not a list. This function should only be used on + short lists as a copy will be created of the list which will not be released until after the + nif returns.</p> + <p>The <c>list_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding)</nametext></name> - <fsummary>Create a string.</fsummary> + <fsummary>Create a string</fsummary> <desc><p>Create a list containing the characters of the null-terminated string <c>string</c> with encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding)</nametext></name> - <fsummary>Create a string.</fsummary> + <fsummary>Create a string</fsummary> <desc><p>Create a list containing the characters of the string <c>string</c> with length <c>len</c> and encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>. Null-characters are treated as any other characters.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_sub_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, size_t pos, size_t size)</nametext></name> - <fsummary>Make a subbinary term.</fsummary> + <fsummary>Make a subbinary term</fsummary> <desc><p>Make a subbinary of binary <c>bin_term</c>, starting at zero-based position <c>pos</c> with a length of <c>size</c> bytes. <c>bin_term</c> must be a binary or bitstring and @@ -1071,7 +1126,7 @@ typedef enum { bytes in <c>bin_term</c>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple(ErlNifEnv* env, unsigned cnt, ...)</nametext></name> - <fsummary>Create a tuple term.</fsummary> + <fsummary>Create a tuple term</fsummary> <desc><p>Create a tuple term of arity <c>cnt</c>. Expects <c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the elements of the tuple.</p></desc> @@ -1085,14 +1140,14 @@ typedef enum { <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name> - <fsummary>Create a tuple term.</fsummary> + <fsummary>Create a tuple term</fsummary> <desc><p>Create a tuple term with length indicated by the function name. Prefer these functions (macros) over the variadic <c>enif_make_tuple</c> to get a compile time error if the number of arguments does not match.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name> - <fsummary>Create a tuple term from an array.</fsummary> + <fsummary>Create a tuple term from an array</fsummary> <desc><p>Create a tuple containing the elements of array <c>arr</c> of length <c>cnt</c>.</p></desc> </func> @@ -1108,6 +1163,72 @@ typedef enum { <fsummary>Create an integer term from an unsigned long int</fsummary> <desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_create(ErlNifEnv *env, ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEntry entry)</nametext></name> + <fsummary>Create a map iterator</fsummary> + <desc><p>Create an iterator for the map <c>map</c> by initializing the + structure pointed to by <c>iter</c>. The <c>entry</c> argument determines + the start position of the iterator: <c>ERL_NIF_MAP_ITERATOR_FIRST</c> or + <c>ERL_NIF_MAP_ITERATOR_LAST</c>. Return true on success or false if + <c>map</c> is not a map.</p> + <p>A map iterator is only useful during the lifetime of the environment + <c>env</c> that the <c>map</c> belongs to. The iterator must be destroyed by + calling <seealso marker="#enif_map_iterator_destroy"> + enif_map_iterator_destroy</seealso>.</p> + <code type="none"> +ERL_NIF_TERM key, value; +ErlNifMapIterator iter; +enif_map_iterator_create(env, my_map, ERL_NIF_MAP_ITERATOR_FIRST); + +while (enif_map_iterator_get_pair(env, &iter, &key, &value)) { + do_something(key,value); + enif_map_iterator_next(env, &iter); +} +enif_map_iterator_destroy(env, &iter); + </code> + <note><p>The key-value pairs of a map have no defined iteration + order. The only guarantee is that the iteration order of a single map + instance is preserved during the lifetime of the environment that the map + belongs to.</p> + </note> + </desc> + </func> + <func><name><ret>void</ret><nametext>enif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Destroy a map iterator</fsummary> + <desc><p>Destroy a map iterator created by + <seealso marker="#enif_map_iterator_create">enif_map_iterator_create</seealso>. + </p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_get_pair(ErlNifEnv *env, ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM *value)</nametext></name> + <fsummary>Get key and value at current map iterator position</fsummary> + <desc><p>Get key and value terms at current map iterator position. + On success set <c>*key</c> and <c>*value</c> and return true. + Return false if the iterator is positioned at head (before first entry) + or tail (beyond last entry).</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_is_head(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Check if map iterator is positioned before first</fsummary> + <desc><p>Return true if map iterator <c>iter</c> is positioned + before first entry.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_is_tail(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Check if map iterator is positioned after last</fsummary> + <desc><p>Return true if map iterator <c>iter</c> is positioned + after last entry.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_next(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Increment map iterator to point to next entry</fsummary> + <desc><p>Increment map iterator to point to next key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the tail (beyond the last + entry).</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_prev(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Decrement map iterator to point to previous entry</fsummary> + <desc><p>Decrement map iterator to point to previous key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the head (before the first + entry).</p></desc> + </func> <func><name><ret>ErlNifMutex *</ret><nametext>enif_mutex_create(char *name)</nametext></name> <fsummary></fsummary> <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_create">erl_drv_mutex_create</seealso>. @@ -1168,19 +1289,32 @@ typedef enum { <c>reload</c> or <c>upgrade</c>.</p> <p>Was previously named <c>enif_get_data</c>.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_raise_exception(ErlNifEnv* env, ERL_NIF_TERM reason)</nametext></name> + <fsummary>Raise a NIF error exception</fsummary> + <desc><p>Create an error exception with the term <c>reason</c> to be returned from a NIF, + and associate it with the environment <c>env</c>. Once a NIF or any function it calls + invokes <c>enif_raise_exception</c>, the runtime ensures that the exception it creates + is raised when the NIF returns, even if the NIF attempts to return a non-exception + term instead. The return value from <c>enif_raise_exception</c> may be used only as + the return value from the NIF that invoked it (directly or indirectly) or be passed + to <seealso marker="#enif_is_exception">enif_is_exception</seealso>, but + not to any other NIF API function.</p> + <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso> + and <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name> - <fsummary>Change the size of a binary.</fsummary> + <fsummary>Change the size of a binary</fsummary> <desc><p>Change the size of a binary <c>bin</c>. The source binary may be read-only, in which case it will be left untouched and a mutable copy is allocated and assigned to <c>*bin</c>. Return true on success, false if memory allocation failed.</p></desc> </func> <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name> - <fsummary>Release a binary.</fsummary> + <fsummary>Release a binary</fsummary> <desc><p>Release a binary obtained from <c>enif_alloc_binary</c>.</p></desc> </func> <func><name><ret>void</ret><nametext>enif_release_resource(void* obj)</nametext></name> - <fsummary>Release a resource object.</fsummary> + <fsummary>Release a resource object</fsummary> <desc><p>Remove a reference to resource object <c>obj</c>obtained from <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. The resource object will be destructed when the last reference is removed. @@ -1256,12 +1390,12 @@ typedef enum { </desc> </func> <func><name><ret>ErlNifPid *</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name> - <fsummary>Get the pid of the calling process.</fsummary> + <fsummary>Get the pid of the calling process</fsummary> <desc><p>Initialize the pid variable <c>*pid</c> to represent the calling process. Return <c>pid</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name> - <fsummary>Send a message to a process.</fsummary> + <fsummary>Send a message to a process</fsummary> <desc><p>Send a message to a process.</p> <taglist> <tag><c>env</c></tag> diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index 09b5493341..c5a1a92b92 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -248,7 +248,7 @@ evaluation), Erlang stops with an error message. Here is an example that seeds the random number generator:</p> <pre> -% <input>erl -eval '{X,Y,Z}' = now(), random:seed(X,Y,Z).'</input></pre> +% <input>erl -eval '{X,Y,Z} = now(), random:seed(X,Y,Z).'</input></pre> <p>This example uses Erlang as a hexadecimal calculator:</p> <pre> % <input>erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\</input> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index c85cbe543d..35e6e55e72 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -30,508 +30,6 @@ </header> <p>This document describes the changes made to the ERTS application.</p> -<section><title>Erts 7.0</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Fix issuing with spaces and quoting in the arguments when - using erlang:open_port spawn_executable on windows. The - behavior now mimics how unix works. This change implies a - backwards incompatibility for how spawn_executable works - on windows.</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-11905</p> - </item> - <item> - <p> - Fix global call trace when hipe compiled code call beam - compiled functions. Tracing of beam functions should now - alway work regardless who the caller is.</p> - <p> - Own Id: OTP-11939</p> - </item> - <item> - <p> - Correct cache alignment for ETS <c>write_concurrency</c> - locks to improve performance by reduced false sharing. - May increase memory footprint for tables with - <c>write_concurrency</c>.</p> - <p> - Own Id: OTP-11974</p> - </item> - <item> - <p> - All possibly blocking operations in the fd/spawn and - terminal driver have been converted to non-blocking - operations. Before this fix it was possible for the VM to - be blocked for a long time if the entity consuming - stdout/stderr did not consume it fast enough.</p> - <p> - Own Id: OTP-12239</p> - </item> - <item> - <p> - Add missing overhead for offheap binaries created from - external format. This fix can improve the garbage - collection of large binaries originating from - <c>binary_to_term</c> or messages from remote nodes.</p> - <p> - Own Id: OTP-12554</p> - </item> - <item> - <p> - Ensure hashing of zero is consistent</p> - <p> Erlang treats positive and negative zero as - equal:</p> - <p> - <c>true = 0.0 =:= 0.0/-1</c></p> - <p>However, Erlangs hash functions: hash, phash and - phash2 did not reflect this behaviour. The hash values - produced by the different hash functions would not be - identical for positive and negative zero.</p> <p>This - change ensures that hash value of positive zero is always - produced regardless of the signedness of the zero float, - i.e.,</p> - <p> - <c>true = erlang:phash2(0.0) =:= - erlang:phash2(0.0/-1)</c></p> - <p> - Own Id: OTP-12641</p> - </item> - <item> - <p> - Ensure NIF term creation disallows illegal floating point - values and too long atoms. Such values will cause a NIF - to throw badarg exception when it returns.</p> - <p> - Own Id: OTP-12655</p> - </item> - <item> - <p> - Fixed building of Map results from match_specs</p> - <p> - A faulty "box-value" entered into the heap which could - cause a segmentation fault in the garbage collector if it - was written on a heap fragment.</p> - <p> - Own Id: OTP-12656</p> - </item> - <item> - <p> - Fix hipe bug when matching a "writable" binary. The bug - has been seen to sometimes cause a failed binary matching - of a correct utf8 character, but other symptoms are also - possible.</p> - <p> - Own Id: OTP-12667</p> - </item> - <item> - <p> - Keep dirty schedulers from waking other schedulers.</p> - <p> - Own Id: OTP-12685</p> - </item> - <item> - <p> - Disable floating point exceptions if the VM is compiled - by clang/llvm. This is a known long-standing problem in - clang/llvm.</p> - <p> - Own Id: OTP-12717</p> - </item> - <item> - <p> - Fix bug in <c>file:sendfile</c> for FreeBSD causing not - the entire file to be sent.</p> - <p> - Own Id: OTP-12720</p> - </item> - </list> - </section> - - - <section><title>Improvements and New Features</title> - <list> - <item> - <p> - Add <c>md5</c> and <c>module</c> entries to - <c>?MODULE:module_info/0/1</c> and remove obsolete entry - 'import'.</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-11940</p> - </item> - <item> - <p> - Debug function <c>erlang:display/1</c> shows content of - binaries and bitstrings, not only the length.</p> - <p> - Own Id: OTP-11941</p> - </item> - <item> - <p>The time functionality of Erlang has been extended. - This both includes a <seealso - marker="time_correction#The_New_Time_API">new - API</seealso> for time, as well as <seealso - marker="time_correction#Time_Warp_Modes">time warp - modes</seealso> which alters the behavior of the system - when system time changes. <em>You are strongly encouraged - to use the new API</em> instead of the old API based on - <seealso - marker="erlang#now/0"><c>erlang:now/0</c></seealso>. - <c>erlang:now/0</c> has been deprecated since it is and - forever will be a scalability bottleneck. For more - information see the <seealso - marker="time_correction">Time and Time - Correction</seealso> chapter of the ERTS User's - Guide.</p> - <p>Besides the API changes and time warp modes a lot of - scalability and performance improvements regarding time - management has been made internally in the runtime - system. Examples of such improvements are scheduler - specific timer wheels, scheduler specific BIF timer - management, parallel retrieval of monotonic time and - system time on systems with primitives that are not - buggy.</p> - <p> - Own Id: OTP-11997</p> - </item> - <item> - <p><c>erlang:function_exported(M, F, A)</c> will now - return <c>true</c> if <c>M:F/A</c> refers to a BIF.</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-12099</p> - </item> - <item> - <p> - New BIF: <c>erlang:get_keys/0</c>, lists all keys - associated with the process dictionary. Note: - <c>erlang:get_keys/0</c> is auto-imported.</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-12151 Aux Id: seq12521 </p> - </item> - <item> - <p> - Make distributed send of large messages yield to improve - real-time characteristics.</p> - <p> - Own Id: OTP-12232</p> - </item> - <item> - <p> - Use high accuracy poll timeouts</p> - <p> - Where available, use poll/select API's that can handle - time resolutions less than 1ms. In the cases where such - API's are not available the timeout is rounded up to the - nearest ms.</p> - <p> - Own Id: OTP-12236</p> - </item> - <item> - <p> - The internal group to user_drv protocol has been changed - to be synchronous in order to guarantee that output sent - to a process implementing the user_drv protocol is - printed before replying. This protocol is used by the - standard_output device and the ssh application when - acting as a client. </p> - <p> - This change changes the previous unlimited buffer when - printing to standard_io and other devices that end up in - user_drv to 1KB.</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-12240</p> - </item> - <item> - <p>The previously introduced "eager check I/O" feature is - now enabled by default.</p> - <p>Eager check I/O can be disabled using the <c>erl</c> - command line argument: <seealso - marker="erl#+secio"><c>+secio false</c></seealso></p> - <p>Characteristics impact compared to previous - default:</p> <list> <item>Lower latency and smoother - management of externally triggered I/O operations.</item> - <item>A slightly reduced priority of externally triggered - I/O operations.</item> </list> - <p> - Own Id: OTP-12254 Aux Id: OTP-12117 </p> - </item> - <item> - <p> - Properly support maps in match_specs</p> - <p> - Own Id: OTP-12270</p> - </item> - <item> - <p> - The notice that a crashdump has been written has been - moved to be printed before the crashdump is generated - instead of afterwords. The wording of the notice has also - been changed.</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-12292</p> - </item> - <item> - <p> - New function <c>ets:take/2</c>. Works the same as - <c>ets:delete/2</c> but also returns the deleted - object(s).</p> - <p> - Own Id: OTP-12309</p> - </item> - <item> - <p> - Tracing with cpu_timestamp option has been enabled on - Linux.</p> - <p> - Own Id: OTP-12366</p> - </item> - <item> - <p> - ets:info/1,2 now contains information about whether - write_concurrency or read_concurrency is enabled.</p> - <p> - Own Id: OTP-12376</p> - </item> - <item> - <p> - Improved usage of <c>gcc</c>'s builtins for atomic memory - access. These are used when no other implementation of - atomic memory operations is available. For example, when - compiling for ARM when <c>libatomic_ops</c> is not - available.</p> - <p> - The largest improvement will be seen when compiling with - a <c>gcc</c> with support for the <c>__atomic_*</c> - builtins (using a <c>gcc</c> of at least version 4.7), - but also when only the legacy <c>__sync_*</c> builtins - are available (using a <c>gcc</c> of at least version - 4.1) an improvement can be seen.</p> - <p> - For more information see the "<seealso - marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP_Configuring_Atomic-Memory-Operations-and-the-VM">Atomic - Memory Operations and the VM</seealso>" section of - <c>$ERL_TOP/HOWTO/INSTALL.md</c>.</p> - <p> - Own Id: OTP-12383</p> - </item> - <item> - <p> - Introduce <c>math:log2/1</c> function to math module.</p> - <p> - Own Id: OTP-12411</p> - </item> - <item> - <p> - Remove perfctr support</p> - <p> - Development of perfctr in the linux kernel ceased in - 2010. The perfctr support code in the Erlang VM is thus - effectively dead code and therefor removed.</p> - <p> - Own Id: OTP-12508</p> - </item> - <item> - <p><c>zlib:inflateChunk/2</c> has been added. It works - like <c>zlib:inflate/2</c>, but decompresses no more data - than will fit in the buffer configured by - <c>zlib:setBufSize/2</c>.</p> - <p> - Own Id: OTP-12548</p> - </item> - <item> - <p> - Use linear search for small select_val arrays</p> - <p> - Own Id: OTP-12555</p> - </item> - <item> - <p> - New BIF ets:update_counter/4 with a default object as - argument, which will be inserted in the table if the key - was not found.</p> - <p> - Own Id: OTP-12563</p> - </item> - <item> - <p> - Export missing types from zlib module</p> - <p> - Own Id: OTP-12584</p> - </item> - <item> - <p> - Use persistent hashmaps for large Maps <p>Maps will use a - persistent hashmap implementation when the number of - pairs in a Map becomes sufficiently large. The change - will occur when a Map reaches 33 pairs in size but this - limit might change in the future.</p></p> - <p>The most significant impact for the user by this - change is speed, and to a lesser degree memory - consumption and introspection of Maps. Memory consumption - size is probalistic but lesser than <c>gb_trees</c> or - <c>dict</c> for instance. Any other impacts will be - transparent for the user except for the following - changes.</p> - <p>Semantics of Maps have changed in two incompatible - ways compared to the experimental implementation in OTP - 17:</p> <list> <item>Hashing of maps is done different by - <c>erlang:phash2/1,2</c>, <c>erlang:phash/1</c> and - <c>erlang:hash/2</c>.</item> <item>Comparing two maps - with ==, /=, =<, <, >= and >, is done - different if the keys contain floating point - numbers.</item> </list> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-12585</p> - </item> - <item> - <p> - Scalability improvement for <seealso - marker="erlang#make_ref/0">erlang:make_ref/0</seealso>, - and other functionality that create references. Each - scheduler now manage its own set of references. By this - no communication at all is needed when creating - references.</p> - <p> - Previous implementation generated a strictly - monotonically increasing sequence of references - corresponding to creation time on the runtime system - instance. This is <em>not</em> the case with current - implementation. You can only expect reference to be - unique. The Erlang/OTP documentation has never mentioned - anything else but the uniqueness property, so this change - <em>is</em> fully compatible. The only reason we've - marked this as a potential incompatibility is since an - early draft for an Erlang specification mentions strict - monotonicity as a property.</p> - <p> - If you need to create data with a strict monotonicity - property use <seealso - marker="erlang#unique_integer/1">erlang:unique_integer([monotonic])</seealso>. - Do <em>not</em> use the deprecated <seealso - marker="erlang:now/0">erlang:now()</seealso>.</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-12610</p> - </item> - <item> - <p> - Enable different abort signal from heart</p> - <p>By using environment variable HEART_KILL_SIGNAL, heart - can now use a different signal to kill the old running - Erlang.</p> - <p>By default the signal is SIGKILL but SIGABRT may also - be used by setting environment variable: - HEART_KILL_SIGNAL=SIGABRT</p> - <p> - Own Id: OTP-12613 Aux Id: seq12826 </p> - </item> - <item> - <p> - Update autconf to latest version 2015-03-04</p> - <p> - Own Id: OTP-12646</p> - </item> - <item> - <p> - Optimization of timers internally in the VM. This include - process timers (<c>receive ... after</c>), port timers - (<c>driver_set_timer()</c>) as well as BIF timers - (<c>erlang:send_after()</c>/<c>erlang:start_timer()</c>).</p> - <p> - Each scheduler thread now has its own lock-free timer - service instead of one locked central service. This - dramatically improves performance of timer management on - systems with a large amount of schedulers and timers.</p> - <p> - The timer service internal data structure has also been - optimized to be able to handle more timers than before. - That is, each timer service is by its self able to handle - more timers without dramatic performance loss than the - old centralized timer service.</p> - <p> - The API of BIF timers has also been extended. Timeout - values are for example no longer limited to 32-bit - integers. For more information see the documentation of - <seealso - marker="erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso>, - <seealso - marker="erlang#send_after/4"><c>erlang:send_after/4</c></seealso>, - <seealso - marker="erlang#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>, - and <seealso - marker="erlang#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p> - <p> - Own Id: OTP-12650 Aux Id: OTP-11997 </p> - </item> - <item> - <p> - Specialize instructions from common assembler patterns</p> - <p>Specialize common instructions of <c>rem</c>, - <c>band</c>, <c>minus</c> and <c>plus</c> in the beam - loader. This will reduce the number of fetches and thus - lessen the instruction dispatch pressure during runtime - and speed up those operations in some common cases.</p> - <p>Specialize move patterns from x-registers to the stack - with a new <c>move_window</c> instruction. This change - will reduce instruction dispatch pressure.</p> - <p> - Own Id: OTP-12690</p> - </item> - <item> - <p> - Fix cross compilation for Android.</p> - <p> - Own Id: OTP-12693</p> - </item> - <item> - <p> - Fix incorrect use of autoconf macro AC_EGREP_CPP, which - could cause faulty configuration if run from a path - containing the string 'yes'.</p> - <p> - Own Id: OTP-12706</p> - </item> - <item> - <p> - Minimal Java version is now 1.6</p> - <p> - Own Id: OTP-12718</p> - </item> - <item> - <p> - Send format and args on process exit to error_logger</p> - <p> - Previously, the emulator would generate a whole string - with values and call the error_logger passing - <c>"~s~n"</c>. This changes it to a format string - containing <c>~p</c> with the respective values as - arguments.</p> - <p> - Own Id: OTP-12735</p> - </item> - </list> - </section> - -</section> - <section><title>Erts 6.4.1</title> <section><title>Fixed Bugs and Malfunctions</title> |