diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/Makefile | 11 | ||||
| -rw-r--r-- | erts/doc/src/alt_dist.xml | 8 | ||||
| -rw-r--r-- | erts/doc/src/driver.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 54 | ||||
| -rw-r--r-- | erts/doc/src/erl_dist_protocol.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 2 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 458 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 250 | ||||
| -rw-r--r-- | erts/doc/src/escript.xml | 217 | ||||
| -rw-r--r-- | erts/doc/src/match_spec.xml | 54 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 494 |
11 files changed, 1306 insertions, 246 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index 3dfefa2001..6578923fe1 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -1,19 +1,19 @@ # # %CopyrightBegin% -# -# Copyright Ericsson AB 1997-2009. All Rights Reserved. -# +# +# Copyright Ericsson AB 1997-2010. All Rights Reserved. +# # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in # compliance with the License. You should have received a copy of the # Erlang Public License along with this software. If not, it can be # retrieved online at http://www.erlang.org/. -# +# # Software distributed under the License is distributed on an "AS IS" # basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See # the License for the specific language governing rights and limitations # under the License. -# +# # %CopyrightEnd% # include $(ERL_TOP)/make/target.mk @@ -45,6 +45,7 @@ XML_REF1_FILES = epmd.xml \ XML_REF3_FILES = \ driver_entry.xml \ + erl_nif.xml \ erl_set_memory_block.xml \ erl_driver.xml \ erl_prim_loader.xml \ diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index a929aec97f..36d83a685b 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -434,7 +434,7 @@ (13) Word received; /* Bytes received */ (14) struct uds_data *partner; /* The partner in an accept/listen pair */ (15) struct uds_data *next; /* Next structure in list */ -(16) /* The input buffer and it's data */ +(16) /* The input buffer and its data */ (17) int buffer_size; /* The allocated size of the input buffer */ (18) int buffer_pos; /* Current position in input buffer */ (19) int header_pos; /* Where the current header is in the @@ -825,7 +825,7 @@ I/O vector itself. One can use this to allocate the binaries for the queue "manually" in the driver, but we'll just fill the binary array with NULL values (line 7) , which will make - the runtime system allocate it's own buffers when we call + the runtime system allocate its own buffers when we call <c><![CDATA[driver_enqv]]></c> (line 37).</p> <p></p> <p>The routine builds an I/O vector containing the header bytes @@ -942,7 +942,7 @@ between invocations of Erlang nodes with the same name.</item> </list> <p>The control interface gets a buffer to return its value in, - but is free to allocate it's own buffer is the provided one is + but is free to allocate its own buffer is the provided one is to small. Here is the code for <c><![CDATA[uds_control]]></c>:</p> <code type="none"><![CDATA[ ( 1) static int uds_control(ErlDrvData handle, unsigned int command, @@ -1042,7 +1042,7 @@ <c><![CDATA[net_kernel:start/1]]></c> function, which is useful as it starts the distribution on a running system, where tracing/debugging can be performed. The <c><![CDATA[net_kernel:start/1]]></c> routine takes a - list as it's single argument. The lists first element should be + list as its single argument. The lists first element should be the node name (without the "@hostname") as an atom, and the second (and last) element should be one of the atoms <c><![CDATA[shortnames]]></c> or <c><![CDATA[longnames]]></c>. In the example case <c><![CDATA[shortnames]]></c> is diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 12c79aee90..006a6160de 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -413,7 +413,7 @@ select(Port, Query) -> <title>Sample asynchronous driver</title> <p>Sometimes database queries can take long time to complete, in our <c><![CDATA[pg_sync]]></c> driver, the emulator - halts while the driver is doing it's job. This is + halts while the driver is doing its job. This is often not acceptable, since no other Erlang processes gets a chance to do anything. To improve on our postgres driver, we reimplement it using the asynchronous diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index bb741c7836..0e26d62548 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -41,6 +41,26 @@ to scroll back to text which has scrolled off the screen. The <c><![CDATA[erl]]></c> program must be used, however, in pipelines or if you want to redirect standard input or output.</p> + <note><p>As of ERTS version 5.8 (OTP-R14A) the runtime system will by + default bind schedulers to logical processors using the + <c>default_bind</c> bind type if the amount of schedulers are + at least equal to the amount of logical processors configured, + binding of schedulers is supported, and a CPU topology is + available at startup. + </p><p> + If the Erlang runtime system is the only operating system + process that binds threads to logical processors, this + improves the performance of the runtime system. However, + if other operating system processes (as for example + another Erlang runtime system) also bind threads to + logical processors, there might be a performance penalty + instead. If this is the case you, are are advised to + unbind the schedulers using the + <seealso marker="#+sbt">+sbtu</seealso> command line argument, + or by invoking + <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, + unbound)</seealso>.</p> + </note> </description> <funcs> <func> @@ -583,6 +603,24 @@ <item> <p>Force ets memory block to be moved on realloc.</p> </item> + <tag><marker id="+rg"><c><![CDATA[+rg ReaderGroupsLimit]]></c></marker></tag> + <item> + <p>Limits the amount of reader groups used by read/write locks + optimized for read operations in the Erlang runtime system. By + default the reader groups limit equals 8.</p> + <p>When the amount of schedulers is less than or equal to the reader + groups limit, each scheduler has its own reader group. When the + amount of schedulers is larger than the reader groups limit, + schedulers share reader groups. Shared reader groups degrades + read lock and read unlock performance while a large amount of + reader groups degrades write lock performance, so the limit is a + tradeoff between performance for read operations and performance + for write operations. Each reader group currently consumes 64 byte + in each read/write lock. Also note that a runtime system using + shared reader groups benefits from <seealso marker="#+sbt">binding + schedulers to logical processors</seealso>, since the reader groups + are distributed better between schedulers.</p> + </item> <tag><marker id="+S"><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></marker></tag> <item> <p>Sets the amount of scheduler threads to create and scheduler @@ -657,6 +695,22 @@ that the <c>+sct</c> flag may have to be passed before the <c>+sbt</c> flag on the command line (in case no CPU topology has been automatically detected).</p> + <p>The runtime system will by default bind schedulers to logical + processors using the <c>default_bind</c> bind type if the amount + of schedulers are at least equal to the amount of logical + processors configured, binding of schedulers is supported, + and a CPU topology is available at startup. + </p> + <p><em>NOTE:</em> If the Erlang runtime system is the only operating + system process that binds threads to logical processors, this + improves the performance of the runtime system. However, if other + operating system processes (as for example another Erlang runtime + system) also bind threads to logical processors, there might be a + performance penalty instead. If this is the case you, are advised + to unbind the schedulers using the <c>+sbtu</c> command line + argument, or by invoking + <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, + unbound)</seealso>.</p> <p>For more information, see <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, SchedulerBindType)</seealso>. </p> diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 5978af178a..1fe7ac7ecd 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -206,7 +206,7 @@ By default EPMD listens on port 4369. <section> <title>Unregister a node from the EPMD</title> <p> - A node unregister itself from the EPMD by simply closing the + A node unregisters itself from the EPMD by simply closing the TCP connection towards EPMD established when the node was registered. </p> </section> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 5061230a33..497a2fa01d 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -781,7 +781,7 @@ typedef struct ErlIOVec { <marker id="driver_get_now"></marker> <p>This function reads a timestamp into the memory pointed to by the parameter <c>now</c>. See the description of <seealso marker="#ErlDrvNowData">ErlDrvNowData</seealso> for - specification of it's fields. </p> + specification of its fields. </p> <p>The return value is 0 unless the <c>now</c> pointer is not valid, in which case it is < 0. </p> </desc> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 0dd46a951a..f7b7b2f346 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -38,6 +38,18 @@ EXPERIMENTAL feature. The interfaces may be changed in any way in coming releases. The plan is however to lift the experimental label and maintain interface backward compatibility from R14B.</p> + <p>Incompatible changes in <em>R14A</em>:</p> + <list> + <item>Environment argument removed for <c>enif_alloc</c>, + <c>enif_realloc</c>, <c>enif_free</c>, <c>enif_alloc_binary</c>, + <c>enif_realloc_binary</c>, <c>enif_release_binary</c>, + <c>enif_alloc_resource</c>, <c>enif_release_resource</c>, + <c>enif_is_identical</c> and <c>enif_compare</c>.</item> + <item>Character encoding argument added to <c>enif_get_atom</c> + and <c>enif_make_existing_atom</c>.</item> + <item>Module argument added to <c>enif_open_resource_type</c> + while changing name spaces of resource types from global to module local.</item> + </list> <p>Incompatible changes in <em>R13B04</em>:</p> <list> <item>The function prototypes of the NIFs have changed to expect <c>argc</c> and <c>argv</c> @@ -109,9 +121,9 @@ ok the new directive <seealso marker="doc/reference_manual:code_loading#on_load">on_load</seealso> to automatically load the NIF library when the module is loaded.</p> - <note><p>A NIF must be exported or used locally by the module (or both). - An unused local stub function will be optimized away by the compiler - causing loading of the NIF library to fail.</p> + <note><p>A NIF does not have to be exported, it can be local to the module. + Note however that unused local stub functions will be optimized + away by the compiler causing loading of the NIF library to fail.</p> </note> <p>A loaded NIF library is tied to the Erlang module code version that loaded it. If the module is upgraded with a new version, the @@ -122,7 +134,7 @@ ok will be shared as well. To avoid unintentionally shared static data, each Erlang module code can keep its own private data. This private data can be set when the NIF library is loaded and - then retrieved by calling <seealso marker="#enif_priv_data">enif_priv_data()</seealso>.</p> + then retrieved by calling <seealso marker="#enif_priv_data">enif_priv_data</seealso>.</p> <p>There is no way to explicitly unload a NIF library. A library will be automatically unloaded when the module code that it belongs to is purged by the code server. A NIF library will also be unloaded if it is replaced @@ -137,14 +149,20 @@ ok <taglist> <tag>Read and write Erlang terms</tag> <item><p>Any Erlang terms can be passed to a NIF as function arguments and - be returned as function return values. The terms are of C-type <c>ERL_NIF_TERM</c> + be returned as function return values. The terms are of C-type + <seealso marker="#ERL_NIF_TERM">ERL_NIF_TERM</seealso> and can only be read or written using API functions. Most functions to read the content of a term are prefixed <c>enif_get_</c> and usually return true (or false) if the term was of the expected type (or not). The functions to write terms are all prefixed <c>enif_make_</c> and usually return the created <c>ERL_NIF_TERM</c>. There are also some functions to query terms, like <c>enif_is_atom</c>, <c>enif_is_identical</c> and - <c>enif_compare</c>.</p></item> + <c>enif_compare</c>.</p> + <p>All terms of type <c>ERL_NIF_TERM</c> belong to an environment of type + <seealso marker="#ErlNifEnv">ErlNifEnv</seealso>. The lifetime of a term is + controlled by the lifetime of its environment object. All API functions that read + or write terms has the environment, that the term belongs to, as the first + function argument.</p></item> <tag>Binaries</tag> <item><p>Terms of type binary are accessed with the help of the struct type <seealso marker="#ErlNifBinary">ErlNifBinary</seealso> @@ -161,8 +179,10 @@ ok <seealso marker="#enif_release_binary">enif_release_binary</seealso> or made read-only by transferring it to an Erlang term with <seealso marker="#enif_make_binary">enif_make_binary</seealso>. - But it does not have do happen in the same NIF call. Read-only binaries - does not have to be released.</p> + But it does not have to happen in the same NIF call. Read-only binaries + do not have to be released.</p> + <p><seealso marker="#enif_make_new_binary">enif_make_new_binary</seealso> + can be used as a shortcut to allocate and return a binary in the same NIF call.</p> <p>Binaries are sequences of whole bytes. Bitstrings with an arbitrary bit length have no support yet.</p> </item> @@ -170,28 +190,29 @@ ok <item><p>The use of resource objects is a way to return pointers to native data structures from a NIF in a safe way. A resource object is just a block of memory allocated with - <seealso marker="#enif_alloc_resource">enif_alloc_resource()</seealso>. + <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of - <seealso marker="#enif_make_resource">enif_make_resource()</seealso>. + <seealso marker="#enif_make_resource">enif_make_resource</seealso>. The term returned by <c>enif_make_resource</c> is totally opaque in nature. It can be stored and passed between processses on the same node, but the only real end usage is to pass it back as argument to a NIF. - The NIF can then do <seealso marker="#enif_get_resource">enif_get_resource()</seealso> + The NIF can then do <seealso marker="#enif_get_resource">enif_get_resource</seealso> and get back a pointer to the memory block that is guaranteed to still be valid. A resource object will not be deallocated until the last handle term has been garbage collected by the VM and the resource has been - released with <seealso marker="#enif_release_resource">enif_release_resource()</seealso> + released with <seealso marker="#enif_release_resource">enif_release_resource</seealso> (not necessarily in that order).</p> <p>All resource objects are created as instances of some <em>resource type</em>. This makes resources from different modules to be distinguishable. A resource type is created by calling - <seealso marker="#enif_open_resource_type">enif_open_resource_type()</seealso> + <seealso marker="#enif_open_resource_type">enif_open_resource_type</seealso> when a library is loaded. Objects of that resource type can then later be allocated and <c>enif_get_resource</c> verifies that the resource is of the expected type. A resource type can have a user supplied destructor function that is automatically called when resources of that type are released (by either the garbage collector or <c>enif_release_resource</c>). Resource types - are uniquely identified by a supplied name string.</p> + are uniquely identified by a supplied name string and the name of the + implementing module.</p> <p>Resource types support upgrade in runtime by allowing a loaded NIF library to takeover an already existing resource type and thereby "inherit" all existing objects of that type. The destructor of the new @@ -199,14 +220,14 @@ ok library with the old destructor function can be safely unloaded. Existing resource objects, of a module that is upgraded, must either be deleted or taken over by the new NIF library. The unloading of a library will be - postponed as long as it exists resource objects with a destructor + postponed as long as there exist resource objects with a destructor function in the library. </p> <p>Here is a template example of how to create and return a resource object.</p> <p/> <code type="none"> ERL_NIF_TERM term; - MyStruct* ptr = enif_alloc_resource(env, my_resource_type, sizeof(MyStruct)); + MyStruct* ptr = enif_alloc_resource(my_resource_type, sizeof(MyStruct)); /* initialize struct ... */ @@ -216,21 +237,31 @@ ok /* store 'ptr' in static variable, private data or other resource object */ } else { - enif_release_resource(env, obj); + enif_release_resource(obj); /* resource now only owned by "Erlang" */ } return term; } </code> - + <p>Another usage of resource objects is to create binary terms with + user defined memory management. + <seealso marker="#enif_make_resource_binary">enif_make_resource_binary</seealso> + will create a binary term that is connected to a resource object. The + destructor of the resource will be called when the binary is garbage + collected, at which time the binary data can be released. An example of + this can be a binary term consisting of data from a <c>mmap</c>'ed file. + The destructor can then do <c>munmap</c> to release the memory + region.</p> </item> <tag>Threads and concurrency</tag> <item><p>A NIF is thread-safe without any explicit synchronization as long as it acts as a pure function and only reads the supplied arguments. As soon as you write towards a shared state either through static variables or <seealso marker="#enif_priv_data">enif_priv_data</seealso> - you need to supply your own explicit synchronization. Resource objects - will also require synchronization if you treat them as mutable.</p> + you need to supply your own explicit synchronization. This includes terms + in process independent environments that are shared between threads. + Resource objects will also require synchronization if you treat them as + mutable.</p> <p>The library initialization callbacks <c>load</c>, <c>reload</c> and <c>upgrade</c> are all thread-safe even for shared state data.</p> <p>Avoid doing lengthy work in NIF calls as that may degrade the @@ -262,8 +293,8 @@ ok <item><p><c>load</c> is called when the NIF library is loaded and there is no previously loaded library for this module.</p> <p><c>*priv_data</c> can be set to point to some private data - that the library needs in able to keep a state between NIF - calls. <c>enif_priv_data()</c> will return this pointer. + that the library needs in order to keep a state between NIF + calls. <c>enif_priv_data</c> will return this pointer. <c>*priv_data</c> will be initialized to NULL when <c>load</c> is called.</p> <p><c>load_info</c> is the second argument to <seealso @@ -315,19 +346,37 @@ ok <item> <p>Variables of type <c>ERL_NIF_TERM</c> can refer to any Erlang term. This is an opaque type and values of it can only by used either as - arguments to API functions or as return values from NIFs. A variable of - type <c>ERL_NIF_TERM</c> is only valid until the NIF call, where it was - obtained, returns.</p> + arguments to API functions or as return values from NIFs. All + <c>ERL_NIF_TERM</c>'s belong to an environment + (<seealso marker="#ErlNifEnv">ErlNifEnv</seealso>). A term can not be + destructed individually, it is valid until its environment is destructed.</p> </item> <tag><marker id="ErlNifEnv"/>ErlNifEnv</tag> <item> - <p><c>ErlNifEnv</c> contains information about the context in - which a NIF call is made. This pointer should not be - dereferenced in any way, but only passed on to API - functions. An <c>ErlNifEnv</c> pointer is only valid until - the function, where is what supplied as argument, - returns. There is thus useless and dangerous to store <c>ErlNifEnv</c> - pointers in between NIF calls.</p> + <p><c>ErlNifEnv</c> represents an environment that can host Erlang terms. + All terms in an environment are valid as long as the environment is valid. + <c>ErlNifEnv</c> is an opaque type and pointers to it can only be passed + on to API functions. There are two types of environments; process + bound and process independent.</p> + <p>A <em>process bound environment</em> is passed as the first argument to all NIFs. + All function arguments passed to a NIF will belong to that environment. + The return value from a NIF must also be a term belonging to the same + environment. + In addition a process bound environment contains transient information + about the calling Erlang process. The environment is only valid in the + thread where it was supplied as argument until the NIF returns. It is + thus useless and dangerous to store pointers to process bound + environments between NIF calls. </p> + <p>A <em>process independent environment</em> is created by calling + <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>. It can be + used to store terms beteen NIF calls and to send terms with + <seealso marker="#enif_send">enif_send</seealso>. A process + 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 + <seealso marker="#enif_make_copy">enif_make_copy</seealso>.</p> </item> <tag><marker id="ErlNifFunc"/>ErlNifFunc</tag> <item> @@ -361,7 +410,18 @@ typedef struct { <p><c>ErlNifBinary</c> contains transient information about an inspected binary term. <c>data</c> is a pointer to a buffer of <c>size</c> bytes with the raw content of the binary.</p> + <p>Note that <c>ErlNifBinary</c> is a semi-opaque type and you are + only allowed to read fields <c>size</c> and <c>data</c>.</p> </item> + <tag><marker id="ErlNifPid"/>ErlNifPid</tag> + <item> + <p><c>ErlNifPid</c> is 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> + </item> + <tag><marker id="ErlNifResourceType"/>ErlNifResourceType</tag> <item> <p>Each instance of <c>ErlNifResourceType</c> represent a class of @@ -386,9 +446,9 @@ typedef enum { ERL_NIF_LATIN1 }ErlNifCharEncoding; </code> - <p>The character encoding used in strings. The only supported - encoding is currently <c>ERL_NIF_LATIN1</c> for iso-latin-1 - (8-bit ascii).</p> + <p>The character encoding used in strings and atoms. The only + supported encoding is currently <c>ERL_NIF_LATIN1</c> for + iso-latin-1 (8-bit ascii).</p> </item> <tag><marker id="ErlNifSysInfo"/>ErlNifSysInfo</tag> <item> @@ -405,24 +465,40 @@ typedef enum { <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(ErlNifEnv* env, unsigned size, ErlNifBinary* bin)</nametext></name> + <func><name><ret>int</ret><nametext>enif_alloc_binary(size_t size, ErlNifBinary* bin)</nametext></name> <fsummary>Create a new binary.</fsummary> - <desc><p>Allocate a new binary of size of <c>size</c> + <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 - <seealso marker="#enif_release_binary">enif_release_binary()</seealso> + <seealso marker="#enif_release_binary">enif_release_binary</seealso> or ownership transferred to an Erlang term with - <seealso marker="#enif_make_binary">enif_make_binary()</seealso>. + <seealso marker="#enif_make_binary">enif_make_binary</seealso>. An allocated (and owned) <c>ErlNifBinary</c> can be kept between NIF calls.</p> - <p>Return false if allocation failed.</p> + <p>Return true on success or false if allocation failed.</p> + </desc> + </func> + <func><name><ret>ErlNifEnv*</ret><nametext>enif_alloc_env()</nametext></name> + <fsummary>Create a new environment</fsummary> + <desc><p>Allocate a new process independent environment. The environment can + be used to hold terms that is not bound to any process. Such terms can + later be copied to a process environment with + <seealso marker="#enif_make_copy">enif_make_copy</seealso> + or be sent to a process as a message with <seealso marker="#enif_send">enif_send</seealso>.</p> + <p>Return pointer to the new environment.</p> </desc> </func> - <func><name><ret>void*</ret><nametext>enif_alloc_resource(ErlNifEnv* env, ErlNifResourceType* type, unsigned size)</nametext></name> + <func><name><ret>void*</ret><nametext>enif_alloc_resource(ErlNifResourceType* type, unsigned size)</nametext></name> <fsummary>Allocate a memory managed resource object</fsummary> <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>int</ret><nametext>enif_compare(ErlNifEnv* env, ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name> + <func><name><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext></name> + <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> + </func> + <func><name><ret>int</ret><nametext>enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name> <fsummary>Compare two terms</fsummary> <desc><p>Return an integer less than, equal to, or greater than zero if <c>lhs</c> is found, respectively, to be less than, @@ -432,77 +508,98 @@ typedef enum { </func> <func><name><ret>void</ret><nametext>enif_cond_broadcast(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_broadcast">erl_drv_cond_broadcast()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_broadcast">erl_drv_cond_broadcast</seealso>. </p></desc> </func> <func><name><ret>ErlNifCond*</ret><nametext>enif_cond_create(char *name)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_create">erl_drv_cond_create()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_create">erl_drv_cond_create</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_cond_destroy(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_destroy">erl_drv_cond_destroy()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_destroy">erl_drv_cond_destroy</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_cond_signal(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_signal">erl_drv_cond_signal()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_signal">erl_drv_cond_signal</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_wait">erl_drv_cond_wait()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_wait">erl_drv_cond_wait</seealso>. </p></desc> </func> <func><name><ret>int</ret><nametext>enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_free(ErlNifEnv* env, void* ptr)</nametext></name> <fsummary>Free dynamic memory</fsummary> <desc><p>Free memory allocated by <c>enif_alloc</c>.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env, - ERL_NIF_TERM term, char* buf, unsigned size) - </nametext></name> + <func><name><ret>void</ret><nametext>enif_free_env(ErlNifEnv* env)</nametext></name> + <fsummary>Free an environment allocated with enif_alloc_env</fsummary> + <desc><p>Free an environment allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>. + All terms created in the environment will be freed as well.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM term, char* buf, unsigned size, ErlNifCharEncoding encode)</nametext></name> <fsummary>Get the text representation of an atom term</fsummary> <desc><p>Write a null-terminated string, in the buffer pointed to by <c>buf</c> of size <c>size</c>, consisting of the string - representation of the atom <c>term</c>. Return the number of bytes - written (including terminating null character) or 0 if + representation of the atom <c>term</c> with encoding + <seealso marker="#ErlNifCharEncoding">encode</seealso>. Return + the number of bytes written (including terminating null character) or 0 if <c>term</c> is not an atom with maximum length of <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> + <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> <desc><p>Set <c>*dp</c> to the floating point value of - <c>term</c> or return false if <c>term</c> is not a float.</p></desc> + <c>term</c>. Return true on success or false if <c>term</c> is not a float.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_int(ErlNifEnv* env, ERL_NIF_TERM term, int* ip)</nametext></name> - <fsummary>Read an integer term.</fsummary> + <fsummary>Read an integer term</fsummary> <desc><p>Set <c>*ip</c> to the integer value of - <c>term</c> or return false if <c>term</c> is not an integer or is - outside the bounds of type <c>int</c></p></desc> + <c>term</c>. Return true on success or false if <c>term</c> is not an + integer or is outside the bounds of type <c>int</c></p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid)</nametext></name> + <fsummary>Read an local pid term</fsummary> + <desc><p>If <c>term</c> is the pid of a node local process, initialize the + pid variable <c>*pid</c> from it and return true. Otherwise return false. + No check if the process is alive is done.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_list_cell(ErlNifEnv* env, ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)</nametext></name> <fsummary>Get head and tail from a list</fsummary> <desc><p>Set <c>*head</c> and <c>*tail</c> from - <c>list</c> or return false if <c>list</c> is not a non-empty - list.</p></desc> + <c>list</c> and return true, or return false if <c>list</c> is not a + 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> + <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> - <desc><p>Set <c>*ip</c> to the long integer value of - <c>term</c> or return false if <c>term</c> is not an integer or is + <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> <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>. - The pointer is valid until the calling NIF returns and should not be released.</p> - <p>Return false if <c>term</c> is not a handle to a resource object + <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 of type <c>type</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env, @@ -527,27 +624,27 @@ typedef enum { <c>*arity</c> to the number of elements. Note that the array is read-only and <c>(*array)[N-1]</c> will be the Nth element of the tuple. <c>*array</c> is undefined if the arity of the tuple - is zero.</p><p>Return false if <c>term</c> is not a + is zero.</p><p>Return true on success or false if <c>term</c> is not a 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> - <desc><p>Set <c>*ip</c> to the unsigned integer value of - <c>term</c> 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> + <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_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name> <fsummary>Read an unsigned integer term.</fsummary> - <desc><p>Set <c>*ip</c> to the unsigned long integer value of - <c>term</c> 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> + <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_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name> <fsummary>Inspect the content of a binary</fsummary> <desc><p>Initialize the structure pointed to by <c>bin</c> with information about the binary term - <c>bin_term</c>. Return false if <c>bin_term</c> is not a binary.</p></desc> + <c>bin_term</c>. Return true on success or false if <c>bin_term</c> is not a binary.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_inspect_iolist_as_binary(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifBinary* bin) @@ -556,7 +653,7 @@ typedef enum { <desc><p>Initialize the structure pointed to by <c>bin</c> with one continuous buffer with the same byte content as <c>iolist</c>. As with inspect_binary, the data pointed to by <c>bin</c> is transient and does - not need to be released. Return false if <c>iolist</c> is not an + not need to be released. Return true on success or false if <c>iolist</c> is not an iolist.</p> </desc> </func> @@ -576,7 +673,7 @@ typedef enum { <fsummary>Determine if a term is a fun</fsummary> <desc><p>Return true if <c>term</c> is a fun.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_is_identical(ErlNifEnv* env, ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name> + <func><name><ret>int</ret><nametext>enif_is_identical(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name> <fsummary>Erlang operator =:=</fsummary> <desc><p>Return true if the two terms are identical. Corresponds to the Erlang operators <c>=:=</c> and @@ -590,15 +687,35 @@ typedef enum { <fsummary>Determine if a term is a port</fsummary> <desc><p>Return true if <c>term</c> is a port.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is a reference</fsummary> <desc><p>Return true if <c>term</c> is a reference.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> + <fsummary>Determine if a term is a tuple</fsummary> + <desc><p>Return true if <c>term</c> is a tuple.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> + <fsummary>Determine if a term is a list</fsummary> + <desc><p>Return true if <c>term</c> is a list.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_keep_resource(void* obj)</nametext></name> + <fsummary>Add a reference to a resource object</fsummary> + <desc><p>Add a reference to resource object <c>obj</c> obtained from + <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. + Each call to <c>enif_keep_resource</c> for an object must be balanced by + a call to <seealso marker="#enif_release_resource">enif_release_resource</seealso> + before the object will be destructed.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom(ErlNifEnv* env, const char* name)</nametext></name> <fsummary>Create an atom term</fsummary> - <desc><p>Create an atom term from the C-string <c>name</c>. Unlike other terms, atom - terms may be saved and used between NIF calls.</p></desc> + <desc><p>Create an atom term from the null-terminated C-string <c>name</c> + with iso-latin-1 encoding.</p></desc> + </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv* env, const char* name, size_t len)</nametext></name> + <fsummary>Create an atom term</fsummary> + <desc><p>Create an atom term from the string <c>name</c> with length <c>len</c>. + Null-characters are treated as any other characters.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name> <fsummary>Make a badarg exception.</fsummary> @@ -611,16 +728,31 @@ typedef enum { <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> + <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> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_double(ErlNifEnv* env, double d)</nametext></name> - <fsummary>Create an floating-point term</fsummary> - <desc><p>Create an floating-point term from a <c>double</c>.</p></desc> + <fsummary>Create a floating-point term</fsummary> + <desc><p>Create a floating-point term from a <c>double</c>.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom)</nametext></name> + <func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode)</nametext></name> <fsummary>Create an existing atom term</fsummary> <desc><p>Try to create the term of an already existing atom from - the C-string <c>name</c>. If the atom already exist store the - term in <c>*atom</c> and return true, otherwise return - false.</p></desc> + the null-terminated C-string <c>name</c> with encoding + <seealso marker="#ErlNifCharEncoding">encode</seealso>. If the atom + already exists store the term in <c>*atom</c> and return true, otherwise + return false.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding)</nametext></name> + <fsummary>Create an existing atom term</fsummary> + <desc><p>Try to create the term of an already existing atom from the + string <c>name</c> with length <c>len</c> and encoding + <seealso marker="#ErlNifCharEncoding">encode</seealso>. Null-characters + are treated as any other characters. If the atom already exists store the term + in <c>*atom</c> and return true, otherwise return false.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int(ErlNifEnv* env, int i)</nametext></name> <fsummary>Create an integer term</fsummary> @@ -644,7 +776,7 @@ typedef enum { <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 compile time error if the number of + <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> @@ -660,6 +792,20 @@ typedef enum { <fsummary>Create an integer term from a long int</fsummary> <desc><p>Create an integer term from a <c>long int</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> + <desc><p>Allocate a binary of size <c>size</c> bytes and create an owning + term. The binary data is mutable until the calling NIF returns. This is a + quick way to create a new binary without having to use + <seealso marker="#ErlNifBinary">ErlNifBinary</seealso>. The drawbacks are + that the binary can not be kept between NIF calls and it can not be + 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_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> <desc><p>Create a reference like <seealso marker="erlang#make_ref-0">erlang:make_ref/0</seealso>.</p></desc> @@ -670,18 +816,47 @@ typedef enum { obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. No ownership transfer is done, the resource object still needs to be released by <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p> - <p>Note that the only defined behaviour when using of a resource term in + <p>Note that the only defined behaviour of using a resource term in an Erlang program is to store it and send it between processes on the same node. Other operations such as matching or <c>term_to_binary</c> will have unpredictable (but harmless) results.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_resource_binary(ErlNifEnv* env, void* obj, const void* data, size_t size)</nametext></name> + <fsummary>Create a custom binary term</fsummary> + <desc><p>Create a binary term that is memory managed by a resource object + <c>obj</c> obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. + The returned binary term will consist of <c>size</c> bytes pointed to + by <c>data</c>. This raw binary data must be kept readable and unchanged + until the destructor of the resource is called. The binary data may be + stored external to the resource object in which case it is the responsibility + of the destructor to release the data.</p> + <p>Several binary terms may be managed by the same resource object. The + destructor will not be called until the last binary is garbage collected. + This can be useful as a way to return different parts of a larger binary + buffer.</p> + <p>As with <seealso marker="#enif_make_resource">enif_make_resource</seealso>, + no ownership transfer is done. The resource still needs to be released with + <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p> + </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> + <desc><p>Initialize the pid variable <c>*pid</c> to represent the + calling process. Return <c>pid</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> <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> + <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, unsigned pos, unsigned size)</nametext></name> + env, ERL_NIF_TERM bin_term, size_t pos, size_t size)</nametext></name> <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. @@ -707,7 +882,7 @@ typedef enum { <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 compile time error if the number of + <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> @@ -725,30 +900,31 @@ typedef enum { </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>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_create">erl_drv_mutex_create</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_mutex_destroy(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_destroy">erl_drv_mutex_destroy()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_destroy">erl_drv_mutex_destroy</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_mutex_lock(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_lock">erl_drv_mutex_lock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_lock">erl_drv_mutex_lock</seealso>. </p></desc> </func> <func><name><ret>int</ret><nametext>enif_mutex_trylock(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_trylock">erl_drv_mutex_trylock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_trylock">erl_drv_mutex_trylock</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_mutex_unlock(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_unlock">erl_drv_mutex_unlock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_unlock">erl_drv_mutex_unlock</seealso>. </p></desc> </func> - <func><name><ret>ErlNifResourceType*</ret><nametext>enif_open_resource_type(ErlNifEnv* env, const char* name, + <func><name><ret>ErlNifResourceType*</ret><nametext>enif_open_resource_type(ErlNifEnv* env, + const char* module_str, const char* name, ErlNifResourceDtor* dtor, ErlNifResourceFlags flags, ErlNifResourceFlags* tried)</nametext></name> <fsummary>Create or takeover a resource type</fsummary> <desc><p>Create or takeover a resource type identified by the string @@ -762,10 +938,10 @@ typedef enum { The supplied destructor <c>dtor</c> will be called both for existing instances as well as new instances not yet created by the calling NIF library.</item> </taglist> - <p>The two flag values can be combined with bitwise-or. To avoid unintentionally - name clashes a good practice is to include the module name as part of the - type <c>name</c>. The <c>dtor</c> may be <c>NULL</c> in case no destructor - is needed.</p> + <p>The two flag values can be combined with bitwise-or. The name of the + resource type is local to the calling module. Argument <c>module_str</c> + is not (yet) used and must be NULL. The <c>dtor</c> may be <c>NULL</c> + in case no destructor is needed.</p> <p>On success, return a pointer to the resource type and <c>*tried</c> will be set to either <c>ERL_NIF_RT_CREATE</c> or <c>ERL_NIF_RT_TAKEOVER</c> to indicate what was actually done. @@ -782,123 +958,151 @@ 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>void</ret><nametext>enif_realloc_binary(ErlNifEnv* env, ErlNifBinary* bin, unsigned size)</nametext></name> + <func><name><ret>void</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name> <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>.</p></desc> </func> - <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name> + <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name> <fsummary>Release a binary.</fsummary> - <desc><p>Release a binary obtained - from <c>enif_alloc_binary</c>.</p></desc> + <desc><p>Release a binary obtained from <c>enif_alloc_binary</c>.</p></desc> </func> - <func><name><ret>void</ret><nametext>enif_release_resource(ErlNifEnv* env, void* obj)</nametext></name> + <func><name><ret>void</ret><nametext>enif_release_resource(void* obj)</nametext></name> <fsummary>Release a resource object.</fsummary> - <desc><p>Release a resource objects obtained from <c>enif_alloc_resource</c>. - The object may still be alive if it is referred to by Erlang terms. Each call to - <c>enif_release_resource</c> must correspond to a previous call to <c>enif_alloc_resource</c>. - References made by <c>enif_make_resource</c> can only be released by the garbage collector.</p></desc> + <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. + Each call to <c>enif_release_resource</c> must correspond to a previous + call to <c>enif_alloc_resource</c> or + <seealso marker="#enif_keep_resource">enif_keep_resource</seealso>. + References made by <seealso marker="#enif_make_resource">enif_make_resource</seealso> + can only be removed by the garbage collector.</p></desc> </func> <func><name><ret>ErlNifRWLock*</ret><nametext>enif_rwlock_create(char *name)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_create">erl_drv_rwlock_create()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_create">erl_drv_rwlock_create</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_rwlock_destroy(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_rwlock_rlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_rwlock_runlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_rwlock_rwlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_rwlock_rwunlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock</seealso>. </p></desc> </func> <func><name><ret>int</ret><nametext>enif_rwlock_tryrlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock</seealso>. </p></desc> </func> <func><name><ret>int</ret><nametext>enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock</seealso>. </p></desc> </func> - <func><name><ret>unsigned</ret><nametext>enif_sizeof_resource(ErlNifEnv* env, void* obj)</nametext></name> + <func><name><ret>unsigned</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> + <desc><p>Send a message to a process.</p> + <taglist> + <tag><c>env</c></tag> + <item>The environment of the calling process. Must be NULL if and + only if calling from a created thread.</item> + <tag><c>*to_pid</c></tag> + <item>The pid of the receiving process. The pid should refer to a process on the local node.</item> + <tag><c>msg_env</c></tag> + <item>The environment of the message term. Must be a process + independent environment allocated with + <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.</item> + <tag><c>msg</c></tag> + <item>The message term to send.</item> + </taglist> + <p>Return true on success, or false if <c>*to_pid</c> does not refer to an alive local process.</p> + <p>The message environment <c>msg_env</c> with all its terms (including + <c>msg</c>) will be invalidated by a successful call to <c>enif_send</c>. The environment + should either be freed with <seealso marker="#enif_free_env">enif_free_env</seealso> + of cleared for reuse with <seealso marker="#enif_clear_env">enif_clear_env</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> + </desc> + </func> + <func><name><ret>unsigned</ret><nametext>enif_sizeof_resource(void* obj)</nametext></name> <fsummary>Get the byte size of a resource object</fsummary> <desc><p>Get the byte size of a resource object <c>obj</c> obtained by - <c>enif_alloc_resource</c>.</p></desc> + <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.</p></desc> </func> <func> <name><ret>void</ret><nametext>enif_system_info(ErlNifSysInfo *sys_info_ptr, size_t size)</nametext></name> <fsummary>Get information about the Erlang runtime system</fsummary> - <desc><p>Same as <seealso marker="erl_driver#driver_system_info">driver_system_info()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#driver_system_info">driver_system_info</seealso>. </p></desc> </func> <func><name><ret>int</ret><nametext>enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_create">erl_drv_thread_create()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_create">erl_drv_thread_create</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_thread_exit(void *resp)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_exit">erl_drv_thread_exit()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_exit">erl_drv_thread_exit</seealso>. </p></desc> </func> <func><name><ret>int</ret><nametext>enif_thread_join(ErlNifTid, void **respp)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_join">erl_drv_thread_join ()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_join">erl_drv_thread_join </seealso>. </p></desc> </func> <func><name><ret>ErlNifThreadOpts*</ret><nametext>enif_thread_opts_create(char *name)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_create">erl_drv_thread_opts_create</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_thread_opts_destroy(ErlNifThreadOpts *opts)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy</seealso>. </p></desc> </func> <func><name><ret>ErlNifTid</ret><nametext>enif_thread_self(void)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_self">erl_drv_thread_self()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_self">erl_drv_thread_self</seealso>. </p></desc> </func> <func><name><ret>int</ret><nametext>enif_tsd_key_create(char *name, ErlNifTSDKey *key)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_create">erl_drv_tsd_key_create()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_create">erl_drv_tsd_key_create</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_tsd_key_destroy(ErlNifTSDKey key)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy</seealso>. </p></desc> </func> <func><name><ret>void*</ret><nametext>enif_tsd_get(ErlNifTSDKey key)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get</seealso>. </p></desc> </func> <func><name><ret>void</ret><nametext>enif_tsd_set(ErlNifTSDKey key, void *data)</nametext></name> <fsummary></fsummary> - <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_set">erl_drv_tsd_set()</seealso>. + <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_set">erl_drv_tsd_set</seealso>. </p></desc> </func> </funcs> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 46f8df4683..579a5a14c6 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -253,6 +253,54 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> + <name>binary_part(Subject, PosLen) -> binary()</name> + <fsummary>Extracts a part of a binary</fsummary> + <type> + <v>Subject = binary()</v> + <v>PosLen = {Start,Length}</v> + <v>Start = int()</v> + <v>Length = int()</v> + </type> + <desc> + <p>Extracts the part of the binary described by <c>PosLen</c>.</p> + + <p>Negative length can be used to extract bytes at the end of a binary:</p> + +<code> +1> Bin = <<1,2,3,4,5,6,7,8,9,10>>. +2> binary_part(Bin,{byte_size(Bin), -5)). +<<6,7,8,9,10>> +</code> + + <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> + + <p><c>Start</c> is zero-based, i.e:</p> +<code> +1> Bin = <<1,2,3>> +2> binary_part(Bin,{0,2}). +<<1,2>> +</code> + + <p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p> + + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> + <name>binary_part(Subject, Start, Length) -> binary()</name> + <fsummary>Extracts a part of a binary</fsummary> + <type> + <v>Subject = binary()</v> + <v>Start = int()</v> + <v>Length = int()</v> + </type> + <desc> + <p>The same as <c>binary_part(Subject, {Pos, Len})</c>.</p> + + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> <name>binary_to_atom(Binary, Encoding) -> atom()</name> <fsummary>Convert from text representation to an atom</fsummary> <type> @@ -318,6 +366,11 @@ iolist() = [char() | binary() | iolist()] corresponding to the bytes from position <c>Start</c> to position <c>Stop</c> in <c>Binary</c>. Positions in the binary are numbered starting from 1.</p> + + <note><p>This function's indexing style of using one-based indices for + binaries is deprecated. New code should use the functions in + the STDLIB module <c>binary</c> instead. They consequently + use the same (zero-based) style of indexing.</p></note> </desc> </func> <func> @@ -354,7 +407,7 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> - <name>erlang:binary_to_term(Binary, Opts) -> term()</name> + <name>binary_to_term(Binary, Opts) -> term()</name> <fsummary>Decode an Erlang external term format binary</fsummary> <type> <v>Opts = [safe]</v> @@ -446,7 +499,7 @@ iolist() = [char() | binary() | iolist()] <name>erlang:cancel_timer(TimerRef) -> Time | false</name> <fsummary>Cancel a timer</fsummary> <type> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> <v>Time = int()</v> </type> <desc> @@ -710,7 +763,7 @@ false</pre> <name>erlang:demonitor(MonitorRef) -> true</name> <fsummary>Stop monitoring</fsummary> <type> - <v>MonitorRef = ref()</v> + <v>MonitorRef = reference()</v> </type> <desc> <p>If <c>MonitorRef</c> is a reference which the calling process @@ -750,7 +803,7 @@ false</pre> <name>erlang:demonitor(MonitorRef, OptionList) -> true|false</name> <fsummary>Stop monitoring</fsummary> <type> - <v>MonitorRef = ref()</v> + <v>MonitorRef = reference()</v> <v>OptionList = [Option]</v> <v>Option = flush</v> <v>Option = info</v> @@ -2107,7 +2160,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>make_ref() -> ref()</name> + <name>make_ref() -> reference()</name> <fsummary>Return an almost unique reference</fsummary> <desc> <p>Returns an almost unique reference.</p> @@ -2156,7 +2209,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:max(Term1, Term2) -> Maximum</name> + <name>max(Term1, Term2) -> Maximum</name> <fsummary>Return the largest of two term</fsummary> <type> <v>Term1 = Term2 = Maximum = term()</v> @@ -2405,7 +2458,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:min(Term1, Term2) -> Minimum</name> + <name>min(Term1, Term2) -> Minimum</name> <fsummary>Return the smallest of two term</fsummary> <type> <v>Term1 = Term2 = Minimum = term()</v> @@ -2591,6 +2644,37 @@ os_prompt%</pre> </desc> </func> <func> + <name>erlang:nif_error(Reason)</name> + <fsummary>Stop execution with a given reason</fsummary> + <type> + <v>Reason = term()</v> + </type> + <desc> + <p>Works exactly like + <seealso marker="#error/1">erlang:error/1</seealso>, + but Dialyzer thinks that this BIF will return an arbitrary term. + When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, Dialyzer + will not generate false warnings.</p> + </desc> + </func> + <func> + <name>erlang:nif_error(Reason, Args)</name> + <fsummary>Stop execution with a given reason</fsummary> + <type> + <v>Reason = term()</v> + <v>Args = [term()]</v> + </type> + <desc> + <p>Works exactly like + <seealso marker="#error/2">erlang:error/2</seealso>, + but Dialyzer thinks that this BIF will return an arbitrary term. + When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, Dialyzer + will not generate false warnings.</p> + </desc> + </func> + <func> <name>node() -> Node</name> <fsummary>Name of the local node</fsummary> <type> @@ -2606,7 +2690,7 @@ os_prompt%</pre> <name>node(Arg) -> Node</name> <fsummary>At which node is a pid, port or reference located</fsummary> <type> - <v>Arg = pid() | port() | ref()</v> + <v>Arg = pid() | port() | reference()</v> <v>Node = node()</v> </type> <desc> @@ -2683,8 +2767,10 @@ os_prompt%</pre> Otherwise, some other point in time is chosen. It is also guaranteed that subsequent calls to this BIF returns continuously increasing values. Hence, the return value from - <c>now()</c> can be used to generate unique time-stamps. It - can only be used to check the local time of day if + <c>now()</c> can be used to generate unique time-stamps, + and if it is called in a tight loop on a fast machine + the time of the node can become skewed.</p> + <p>It can only be used to check the local time of day if the time-zone info of the underlying operating system is properly configured.</p> </desc> @@ -2749,7 +2835,7 @@ os_prompt%</pre> <item> <p>Works like <c>{spawn, Command}</c>, but only runs - external executables. The <c>Command</c> in it's whole + external executables. The <c>Command</c> in its whole is used as the name of the executable, including any spaces. If arguments are to be passed, the <c>args</c> and <c>arg0</c> <c>PortSettings</c> can be used.</p> @@ -2926,7 +3012,7 @@ os_prompt%</pre> The standard input and standard output handles of the port program will, if this option is supplied, be opened with the flag FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do - overlapped I/O on it's standard handles. This is not normally + overlapped I/O on its standard handles. This is not normally the case for simple port programs, but an option of value for the experienced Windows programmer. <em>On all other platforms, this option is silently discarded</em>.</p> @@ -3147,7 +3233,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:port_command(Port, Data, OptionList) -> true|false</name> + <name>port_command(Port, Data, OptionList) -> true|false</name> <fsummary>Send data to a port</fsummary> <type> <v>Port = port() | atom()</v> @@ -3183,10 +3269,6 @@ os_prompt%</pre> <note> <p>More options may be added in the future.</p> </note> - <note> - <p><c>erlang:port_command/3</c> is currently not auto imported, but - it is planned to be auto imported in OTP R14.</p> - </note> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> @@ -4016,7 +4098,7 @@ os_prompt%</pre> <name>erlang:read_timer(TimerRef) -> int() | false</name> <fsummary>Number of milliseconds remaining for a timer</fsummary> <type> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p><c>TimerRef</c> is a timer reference returned by @@ -4039,7 +4121,7 @@ os_prompt%</pre> <name>erlang:ref_to_list(Ref) -> string()</name> <fsummary>Text representation of a reference</fsummary> <type> - <v>Ref = ref()</v> + <v>Ref = reference()</v> </type> <desc> <p>Returns a string which corresponds to the text @@ -4218,7 +4300,7 @@ true</pre> <v>Dest = pid() | RegName </v> <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> <v>Msg = term()</v> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p>Starts a timer which will send the message <c>Msg</c> @@ -4747,7 +4829,7 @@ true</pre> <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> <v> RegName = atom()</v> <v>Msg = term()</v> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p>Starts a timer which will send the message @@ -5103,10 +5185,21 @@ true</pre> For more information on how to define the CPU topology, see <seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>. </p> - <p><em>NOTE:</em> If other programs on the system have bound - to processors, e.g. another Erlang runtime system, you - may loose performance when binding schedulers. Therefore, - schedulers are by default not bound.</p> + <p>The runtime system will by default bind schedulers to logical + processors using the <c>default_bind</c> bind type if the amount + of schedulers are at least equal to the amount of logical + processors configured, binding of schedulers is supported, + and a CPU topology is available at startup. + </p> + <p><em>NOTE:</em> If the Erlang runtime system is the only + operating system process that binds threads to logical processors, + this improves the performance of the runtime system. However, + if other operating system processes (as for example another Erlang + runtime system) also bind threads to logical processors, there + might be a performance penalty instead. If this is the case you, + are are advised to unbind the schedulers using the + <seealso marker="erl#+sbt">+sbtu</seealso> command line argument, + or <c>erlang:system_flag(scheduler_bind_type, unbound)</c>.</p> <p>Schedulers can be bound in different ways. The <c>How</c> argument determines how schedulers are bound. <c>How</c> can currently be one of:</p> @@ -5271,7 +5364,7 @@ true</pre> <p>Returns <c>{Allocator, Version, Features, Settings}.</c></p> <p>Types:</p> <list type="bulleted"> - <item><c>Allocator = undefined | elib_malloc | glibc</c></item> + <item><c>Allocator = undefined | glibc</c></item> <item><c>Version = [int()]</c></item> <item><c>Features = [atom()]</c></item> <item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item> @@ -5286,7 +5379,7 @@ true</pre> implementation used. If <c>Allocator</c> equals <c>undefined</c>, the <c>malloc()</c> implementation used could not be identified. Currently - <c>elib_malloc</c> and <c>glibc</c> can be identified.</p> + <c>glibc</c> can be identified.</p> </item> <item> <p><c>Version</c> is a list of integers (but not a @@ -5513,52 +5606,9 @@ true</pre> </item> <tag><c>elib_malloc</c></tag> <item> - <p>If the emulator uses the <c>elib_malloc</c> memory - allocator, a list of two-element tuples containing status - information is returned; otherwise, <c>false</c> is - returned. The list currently contains the following - two-element tuples (all sizes are presented in bytes):</p> - <taglist> - <tag><c>{heap_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current heap size.</p> - </item> - <tag><c>{max_alloced_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the maximum amount of memory - allocated on the heap since the emulator started.</p> - </item> - <tag><c>{alloced_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current amount of memory - allocated on the heap.</p> - </item> - <tag><c>{free_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current amount of free - memory on the heap.</p> - </item> - <tag><c>{no_alloced_blocks, No}</c></tag> - <item> - <p>Where <c>No</c> is the current number of allocated - blocks on the heap.</p> - </item> - <tag><c>{no_free_blocks, No}</c></tag> - <item> - <p>Where <c>No</c> is the current number of free blocks - on the heap.</p> - </item> - <tag><c>{smallest_alloced_block, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the size of the smallest - allocated block on the heap.</p> - </item> - <tag><c>{largest_free_block, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the size of the largest free - block on the heap.</p> - </item> - </taglist> + <p>This option will be removed in a future release. + The return value will always be <c>false</c> since + the elib_malloc allocator has been removed.</p> </item> <tag><c>fullsweep_after</c></tag> <item> @@ -5850,9 +5900,23 @@ true</pre> </item> <tag><c>wordsize</c></tag> <item> - <p>Returns the word size in bytes as an integer, i.e. on a - 32-bit architecture 4 is returned, and on a 64-bit - architecture 8 is returned.</p> + <p>Same as <c>{wordsize, internal}</c></p> + </item> + <tag><c>{wordsize, internal}</c></tag> + <item> + <p>Returns the size of Erlang term words in bytes as an + integer, i.e. on a 32-bit architecture 4 is returned, + and on a pure 64-bit architecture 8 is returned. On a + halfword 64-bit emulator, 4 is returned, as the Erlang + terms are stored using a virtual wordsize of half the + systems wordsize.</p> + </item> + <tag><c>{wordsize, external}</c></tag> + <item> + <p>Returns the true wordsize of the emulator, i.e. the size + of a pointer, in bytes as an integer. On a pure 32-bit + architecture 4 is returned, on both a halfword and pure + 64-bit architecture, 8 is returned.</p> </item> </taglist> <note> @@ -6645,6 +6709,17 @@ true</pre> See also <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> </item> + <tag><c>call_time</c></tag> + <item> + <p>Return the call time values for this function or + <c>true</c> for the pseudo function <c>on_load</c> if call + time tracing is active. Returns <c>false</c> otherwise. + The call time values returned, <c>[{Pid, Count, S, Us}]</c>, + is a list of each process that has executed the function and its specific counters. + See also + <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> + </item> + <tag><c>all</c></tag> <item> <p>Return a list containing the <c>{Item, Value}</c> tuples @@ -6747,13 +6822,13 @@ true</pre> </item> <tag><c>restart</c></tag> <item> - <p>For the <c>FlagList</c> option <c>call_count</c>: + <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: restart the existing counters. The behaviour is undefined for other <c>FlagList</c> options.</p> </item> <tag><c>pause</c></tag> <item> - <p>For the <c>FlagList</c> option <c>call_count</c>: pause + <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: pause the existing counters. The behaviour is undefined for other <c>FlagList</c> options.</p> </item> @@ -6808,6 +6883,23 @@ true</pre> <p>The counter value can be read with <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> </item> + <tag><c>call_time</c></tag> + <item> + <p>Starts (<c>MatchSpec == true</c>) or stops + (<c>MatchSpec == false</c>) call time tracing for all + types of function calls. For every function a counter is + incremented when the function is called. Time spent in the function + is accumulated in two other counters, seconds and micro-seconds. + The counters are stored for each call traced process.</p> + <p>If call time tracing is started while already running, + the count and time is restarted from zero. Running counters can be + paused with <c>MatchSpec == pause</c>. Paused and running + counters can be restarted from zero with + <c>MatchSpec == restart</c>.</p> + <p>The counter value can be read with + <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> + </item> + </taglist> <p>The <c>global</c> and <c>local</c> options are mutually exclusive and <c>global</c> is the default (if no options are @@ -6815,7 +6907,7 @@ true</pre> perform a kind of local tracing, and can also not be combined with <c>global</c>. A function can be either globally or locally traced. If global tracing is specified for a - specified set of functions; local, meta and call count + specified set of functions; local, meta, call time and call count tracing for the matching set of local functions will be disabled, and vice versa.</p> <p>When disabling trace, the option must match the type of trace diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index a89449df23..44c9a5ac68 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -31,7 +31,7 @@ <com>escript</com> <comsummary>Erlang scripting support</comsummary> <description> - <p><c><![CDATA[escript]]></c> provides support for running short Erlang programs + <p><c>escript</c> provides support for running short Erlang programs without having to compile them first and an easy way to retrieve the command line arguments.</p> </description> @@ -41,10 +41,10 @@ <name>escript escript-flags script-name script-arg1 script-arg2...</name> <fsummary>Run a script written in Erlang</fsummary> <desc> - <p><c><![CDATA[escript]]></c> runs a script written in Erlang.</p> + <p><c>escript</c> runs a script written in Erlang.</p> <p>Here follows an example.</p> <pre> -$ <input>cat factorial</input> +$ <input>cat factorial</input> #!/usr/bin/env escript %% -*- erlang -*- %%! -smp enable -sname factorial -mnesia debug verbose @@ -59,11 +59,11 @@ main([String]) -> end; main(_) -> usage(). - + usage() -> io:format("usage: factorial integer\n"), halt(1). - + fac(0) -> 1; fac(N) -> N * fac(N-1). $ <input>factorial 5</input> @@ -74,9 +74,8 @@ $ <input>factorial five</input> usage: factorial integer </pre> <p>The header of the Erlang script in the example differs from a normal Erlang module. The first line is intended to be the - interpreter line, which invokes - <c><![CDATA[escript]]></c>. However if you invoke the - <c><![CDATA[escript]]></c> like this</p> + interpreter line, which invokes <c>escript</c>. However if you + invoke the <c>escript</c> like this</p> <pre> $ <input>escript factorial 5</input> </pre> <p>the contents of the first line does not matter, but it @@ -93,13 +92,13 @@ $ <input>escript factorial 5</input> </pre> %%! -smp enable -sname factorial -mnesia debug verbose</pre> <p>Such an argument line must start with <c>%%!</c> and the rest of the line will interpreted as arguments to the emulator.</p> - <p>If you know the location of the <c><![CDATA[escript]]></c> executable, the first - line can directly give the path to <c><![CDATA[escript]]></c>. For instance:</p> + <p>If you know the location of the <c>escript</c> executable, the first + line can directly give the path to <c>escript</c>. For instance:</p> <pre> #!/usr/local/bin/escript </pre> <p>As any other kind of scripts, Erlang scripts will not work on Unix platforms if the execution bit for the script file is not set. - (Use <c><![CDATA[chmod +x script-name]]></c> to turn on the execution bit.) + (Use <c>chmod +x script-name</c> to turn on the execution bit.) </p> <p>The rest of the Erlang script file may either contain @@ -108,33 +107,33 @@ $ <input>escript factorial 5</input> </pre> <p>An Erlang script file must always contain the function <em>main/1</em>. When the script is run, the - <c><![CDATA[main/1]]></c> function will be called with a list + <c>main/1</c> function will be called with a list of strings representing the arguments given to the script (not changed or interpreted in any way).</p> - <p>If the <c><![CDATA[main/1]]></c> function in the script returns successfully, + <p>If the <c>main/1</c> function in the script returns successfully, the exit status for the script will be 0. If an exception is generated during execution, a short message will be printed and the script terminated with exit status 127.</p> - <p>To return your own non-zero exit code, call <c><![CDATA[halt(ExitCode)]]></c>; + <p>To return your own non-zero exit code, call <c>halt(ExitCode)</c>; for instance:</p> <pre> halt(1).</pre> - <p>Call <c><![CDATA[escript:script_name/0]]></c> from your to - script to retrieve the pathname of the script (the pathname - is usually, but not always, absolute).</p> + <p>Call <seealso marker="#script_name_0">escript:script_name()</seealso> + from your to script to retrieve the pathname of the script + (the pathname is usually, but not always, absolute).</p> <p>If the file contains source code (as in the example above), it will be processed by the preprocessor <c>epp</c>. This means that you for example may use pre-defined macros (such as - <c><![CDATA[?MODULE]]></c>) as well as include directives like - the <c><![CDATA[-include_lib]]></c> directive. For instance, use</p> + <c>?MODULE</c>) as well as include directives like + the <c>-include_lib</c> directive. For instance, use</p> <pre> --include_lib("kernel/include/file.hrl"). </pre> +-include_lib("kernel/include/file.hrl").</pre> <p>to include the record definitions for the records used by the - <c><![CDATA[file:read_link_info/1]]></c> function.</p> + <c>file:read_link_info/1</c> function.</p> <p>The script will be checked for syntactic and semantic correctness before being run. If there are warnings (such as @@ -144,7 +143,7 @@ halt(1).</pre> 127.</p> <p>Both the module declaration and the export declaration of - the <c><![CDATA[main/1]]></c> function are optional.</p> + the <c>main/1</c> function are optional.</p> <p>By default, the script will be interpreted. You can force it to be compiled by including the following line somewhere @@ -198,6 +197,180 @@ factorial 5 = 120 </pre> </desc> </func> + <func> + <name>escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error, term()}</name> + <fsummary>Create an escript</fsummary> + <type> + <v>FileOrBin = filename() | 'binary'</v> + <v>Sections = [Header] Body | Body</v> + <v>Header = shebang | {shebang, Shebang} + | comment | {comment, Comment} + | {emu_args, EmuArgs}</v> + <v>Shebang = string() | 'default' | 'undefined'</v> + <v>Comment = string() | 'default' | 'undefined'</v> + <v>EmuArgs = string() | 'undefined'</v> + <v>Body = {source, SourceCode} + | {beam, BeamCode} + | {archive, ZipArchive}</v> + <v>SourceCode = BeamCode = ZipArchive = binary()</v> + </type> + <desc> + <p>The <marker id="create_2"></marker> <c>create/2</c> + function creates an escript from a list of sections. The + sections can be given in any order. An escript begins with an + optional <c>Header</c> followed by a mandatory <c>Body</c>. If + the header is present, it does always begin with a + <c>shebang</c>, possibly followed by a <c>comment</c> and + <c>emu_args</c>. The <c>shebang</c> defaults to + <c>"/usr/bin/env escript"</c>. The comment defaults to + <c>"This is an -*- erlang -*- file"</c>. The created escript + can either be returned as a binary or written to file.</p> + + <p>As an example of how the function can be used, we create an + interpreted escript which uses emu_args to set some emulator + flag. In this case it happens to disable the smp_support. We + do also extract the different sections from the newly created + script:</p> + <pre> +> <input>Source = "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n".</input> +"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n" +> <input>io:format("~s\n", [Source]).</input> +%% Demo +main(_Args) -> + io:format(erlang:system_info(smp_support)). + +ok +> <input>{ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "-smp disable"}, + {source, list_to_binary(Source)}]).</input> +{ok,<<"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!-smp disabl"...>>} +> <input>file:write_file("demo.escript", Bin).</input> +ok +> <input>os:cmd("escript demo.escript").</input> +"false" +> <input>escript:extract("demo.escript", []).</input> +{ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"}, + {source,<<"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...>>}]} + </pre> + + <p>An escript without header can be created like this:</p> +<pre> +> <input>file:write_file("demo.erl", + ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).</input> +ok +> <input>{ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).</input> +{ok,demo, + <<70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0, + 79,0,0,0,9,4,100,...>>} +> <input>escript:create("demo.beam", [{beam, BeamCode}]).</input> +ok +> <input>escript:extract("demo.beam", []).</input> +{ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined}, + {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116, + 111,109,0,0,0,83,0,0,0,9,...>>}]} +> <input>os:cmd("escript demo.beam").</input> +"true" +</pre> + <p>Here we create an archive script containing both Erlang + code as well as beam code. Then we iterate over all files in + the archive and collect their contents and some info about + them. + </p> +<pre> +> <input>{ok, SourceCode} = file:read_file("demo.erl").</input> +{ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>} +> <input>escript:create("demo.escript", + [shebang, + {archive, [{"demo.erl", SourceCode}, + {"demo.beam", BeamCode}], []}]).</input> +ok +> <input>{ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, + {archive, ArchiveBin}]} = escript:extract("demo.escript", []).</input> +{ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined}, + {{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105, + 152,61,93,107,0,0,0,118,0,...>>}]} +> <input>file:write_file("demo.zip", ArchiveBin).</input> +ok +> <input>zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").</input> +{ok,[{"demo.beam", + {file_info,748,regular,read_write, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + 54,1,0,0,0,0,0}, + <<70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0, + 83,0,0,...>>}, + {"demo.erl", + {file_info,118,regular,read_write, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + {{2010,3,2},{0,59,22}}, + 54,1,0,0,0,0,0}, + <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}</pre> + </desc> + </func> + <func> + <name>escript:extract(File, Options) -> {ok, Sections} | {error, term()}</name> + <fsummary>Parses an escript and extracts its sections</fsummary> + <type> + <v>File = filename()</v> + <v>Options = [] | [compile_source]</v> + <v>Sections = Headers Body</v> + <v>Headers = {shebang, Shebang} + {comment, Comment} + {emu_args, EmuArgs}</v> + <v>Shebang = string() | 'default' | 'undefined'</v> + <v>Comment = string() | 'default' | 'undefined'</v> + <v>EmuArgs = string() | 'undefined'</v> + <v>Body = {source, SourceCode} + | {source, BeamCode} + | {beam, BeamCode} + | {archive, ZipArchive}</v> + <v>SourceCode = BeamCode = ZipArchive = binary()</v> + </type> + <desc> + <p>The <marker id="extract_2"></marker> <c>extract/2</c> + function parses an escript and extracts its sections. This is + the reverse of <c>create/2</c>.</p> + + <p>All sections are returned even if they do not exist in the + escript. If a particular section happens to have the same + value as the default value, the extracted value is set to the + atom <c>default</c>. If a section is missing, the extracted + value is set to the atom <c>undefined</c>. </p> + + <p>The <c>compile_source</c> option only affects the result if + the escript contains <c>source</c> code. In that case the + Erlang code is automatically compiled and <c>{source, + BeamCode}</c> is returned instead of <c>{source, + SourceCode}</c>.</p> + + <pre> +> <input>escript:create("demo.escript", + [shebang, {archive, [{"demo.erl", SourceCode}, + {"demo.beam", BeamCode}], []}]).</input> +ok +> <input>{ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, + {archive, ArchiveBin}]} = + escript:extract("demo.escript", []).</input> +{ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105, + 152,61,93,107,0,0,0,118,0,...>>} + {emu_args,undefined}]} + </pre> + </desc> + </func> + <func> + <name>escript:script_name() -> File</name> + <fsummary>Returns the name of an escript</fsummary> + <type> + <v>File = filename()</v> + </type> + <desc> + <p>The <marker id="script_name_0"></marker> + <c>script_name/0</c> function returns the name of the escript + being executed. If the function is invoked outside the context + of an escript, the behavior is undefined.</p> + </desc> + </func> </funcs> <section> diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml index b9f955e4db..f0390c9db8 100644 --- a/erts/doc/src/match_spec.xml +++ b/erts/doc/src/match_spec.xml @@ -60,7 +60,7 @@ <section> <title>Grammar</title> - <p>A match_spec can be described in this <em>informal</em> grammar:</p> + <p>A match_spec used in tracing can be described in this <em>informal</em> grammar:</p> <list type="bulleted"> <item>MatchExpression ::= [ MatchFunction, ... ] </item> @@ -117,6 +117,52 @@ <c><![CDATA[display]]></c> | <c><![CDATA[caller]]></c> | <c><![CDATA[set_tcw]]></c> | <c><![CDATA[silent]]></c></item> </list> + + <p>A match_spec used in ets can be described in this <em>informal</em> grammar:</p> + <list type="bulleted"> + <item>MatchExpression ::= [ MatchFunction, ... ] + </item> + <item>MatchFunction ::= { MatchHead, MatchConditions, MatchBody } + </item> + <item>MatchHead ::= MatchVariable | <c><![CDATA['_']]></c> | { MatchHeadPart, ... } + </item> + <item>MatchHeadPart ::= term() | MatchVariable | <c><![CDATA['_']]></c></item> + <item>MatchVariable ::= '$<number>' + </item> + <item>MatchConditions ::= [ MatchCondition, ...] | <c><![CDATA[[]]]></c></item> + <item>MatchCondition ::= { GuardFunction } | + { GuardFunction, ConditionExpression, ... } + </item> + <item>BoolFunction ::= <c><![CDATA[is_atom]]></c> | <c><![CDATA[is_constant]]></c> | + <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | <c><![CDATA[is_list]]></c> | + <c><![CDATA[is_number]]></c> | <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> | + <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | <c><![CDATA[is_binary]]></c> | + <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> | + <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> | + <c><![CDATA[andalso]]></c> | <c><![CDATA[orelse]]></c></item> + <item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } | + { GuardFunction, ConditionExpression, ... } | TermConstruct + </item> + <item>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) | + <c><![CDATA['$_']]></c> | <c><![CDATA['$$']]></c></item> + <item>TermConstruct = {{}} | {{ ConditionExpression, ... }} | + <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | NonCompositeTerm | Constant + </item> + <item>NonCompositeTerm ::= term() (not list or tuple) + </item> + <item>Constant ::= {<c><![CDATA[const]]></c>, term()} + </item> + <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> | + <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> | <c><![CDATA[length]]></c> | <c><![CDATA[node]]></c> | + <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> | <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> | + <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> | <c><![CDATA['*']]></c> | <c><![CDATA['div']]></c> | + <c><![CDATA['rem']]></c> | <c><![CDATA['band']]></c> | <c><![CDATA['bor']]></c> | <c><![CDATA['bxor']]></c> | + <c><![CDATA['bnot']]></c> | <c><![CDATA['bsl']]></c> | <c><![CDATA['bsr']]></c> | <c><![CDATA['>']]></c> | + <c><![CDATA['>=']]></c> | <c><![CDATA['<']]></c> | <c><![CDATA['=<']]></c> | <c><![CDATA['=:=']]></c> | + <c><![CDATA['==']]></c> | <c><![CDATA['=/=']]></c> | <c><![CDATA['/=']]></c> | <c><![CDATA[self]]></c> | + <c><![CDATA[get_tcw]]></c></item> + <item>MatchBody ::= [ ConditionExpression, ... ]</item> + </list> </section> <section> @@ -453,8 +499,8 @@ <section> <title>Differences between match specifications in ETS and tracing</title> <p>ETS match specifications are there to produce a return - value. Usually the expression contains one single - <c><![CDATA[ActionTerm]]></c> which defines the return value without having + value. Usually the <c><![CDATA[MatchBody]]></c> contains one single + <c><![CDATA[ConditionExpression]]></c> which defines the return value without having any side effects. Calls with side effects are not allowed in the ETS context.</p> <p>When tracing there is no return value to produce, the @@ -530,7 +576,7 @@ the atom 'strider' and the tuple arity is 3 and return the whole object.</p> <code type="none"><![CDATA[ -[{{strider,'_'.'_'}, +[{{strider,'_','_'}, [], ['$_']}] ]]></code> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 824ad6d94e..6174917807 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -30,6 +30,496 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<section><title>Erts 5.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Driver threads, such as async threads, using <seealso + marker="erl_driver#ErlDrvPDL">port data locks</seealso> + peeked at the port status field without proper locking + when looking up the driver queue.</p> + <p> + Own Id: OTP-8475</p> + </item> + <item> + <p> + The use of <c>mmap()</c> was unnecessarily disabled when + cross compiling.</p> + <p> + The <c>configure</c> arguments <c>--with-ssl</c>, and + <c>--with-odbc</c> refused to accept libraries outside of + <c>$erl_xcomp_sysroot</c> when cross compiling for no + good reason.</p> + <p> + The <c>configure</c> argument <c>--with-odbc</c> didn't + handle the value <c>yes</c> correct.</p> + <p> + The <c>configure</c> arguments <c>--with-odbc</c>, and + <c>--without-odbc</c> have also been added to the + configure help.</p> + <p> + (Thanks to Steve Vinoski for reporting these issues)</p> + <p> + Own Id: OTP-8484</p> + </item> + <item> + <p> + A call to the BIF <c>unregister(RegName)</c> when a port + had the name <c>RegName</c> registered in the runtime + system without SMP support caused a runtime system crash. + (Thanks to Per Hedeland for the bugfix and test case.)</p> + <p> + Own Id: OTP-8487</p> + </item> + <item> + <p> + The runtime system crashed if fewer logical processors + were found than reported by <c>sysconf( + SC_NPROCESSORS_CONF)</c>.</p> + <p> + Own Id: OTP-8549</p> + </item> + <item> + <p> + Fix memory management bug causing crash of non-SMP + emulator with async threads enabled. The bug did first + appear in R13B03.</p> + <p> + Own Id: OTP-8591 Aux Id: seq11554 </p> + </item> + <item> + <p> + Port locks could be prematurely destroyed.</p> + <p> + Own Id: OTP-8612</p> + </item> + <item> + <p>The <c>empd</c> program could loop and consume 100% + CPU time if an unexpected error ocurred in + <c>listen()</c> or <c>accept()</c>. Now <c>epmd</c> will + terminate if a non-recoverable error occurs. (Thanks to + Michael Santos.)</p> + <p> + Own Id: OTP-8618</p> + </item> + <item> + <p> + When kernel poll has been enabled, a livelock could in + rare circumstances occur. Problem reported by Chetan + Ahuja, fix by Mikael Pettersson.</p> + <p> + Own Id: OTP-8632</p> + </item> + <item> + <p> + Windows: Closing port of program that stalled without + reading all data could deadlock scheduler thread.</p> + <p> + Own Id: OTP-8641</p> + </item> + <item> + <p> + On some combination of Montavista Linux on Cavium Octeon + processors, some socket-related system calls returned + other numbers than -1 for errors. This caused a core dump + in inet_drv.c. Now the code works around this problem.</p> + <p> + Own Id: OTP-8654</p> + </item> + <item> + <p> + Missing memory barriers in <c>erts_poll()</c> could cause + the runtime system to hang indefinitely.</p> + <p> + Own Id: OTP-8658</p> + </item> + <item> + <p> + <c>ethr_rwmutex_tryrlock()</c> acquired and refused to + acquire a lock with inverted logic. The lock was however + never acquired in a thread unsafe manner. (Thanks to JR + Zhang for noting this issue)</p> + <p> + Own Id: OTP-8662</p> + </item> + <item> + <p> + Extreme combinations of register/unregister in a highly + parallell SMP application could crash the VM. The error + is corrected.</p> + <p> + Own Id: OTP-8663</p> + </item> + <item> + <p> + On Windows, files are now opened with FILE_SHARE_DELETE + to get closer to Unix semantics.</p> + <p> + Own Id: OTP-8667</p> + </item> + <item> + <p> + <c>erlang:system_info(multi_scheduling)</c> sometimes + erroneously returned <c>enabled</c> when it should have + returned <c>blocked</c>.</p> + <p> + Own Id: OTP-8675</p> + </item> + <item> + <p> + Fix bug causing <c>erlang:decode_packet</c> and + <c>enif_make_string</c> to generate faulty strings with + negative character values for ascii values larger than + 127. (Thanks to Paul Guyot)</p> + <p> + Own Id: OTP-8685</p> + </item> + <item> + <p> + <c>open_port/2</c> with the <c>spawn</c> and + <c>spawn_executable</c> options can include an + <c>{env,Env}</c> option. In some cases unsetting + variables would not work on Unix (typically if more + variables were unset than were actually present in the + environment).</p> + <p> + Own Id: OTP-8701</p> + </item> + <item> + <p> + A user defined CPU topology set via a call to <seealso + marker="erlang#system_flag_cpu_topology">erlang:system_flag(cpu_topology, + CPUTopology)</seealso> was not properly verified, and + could in worst case cause an emulator crash. The emulator + crash could only occur when a user defined CPU topology + already existed and was redefined.</p> + <p> + Own Id: OTP-8710</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The grammar for match specifications in ERTS users guide + only described the tracing dialect of match + specifications. An informal grammar for the ETS dialect + is added.</p> + <p> + Own Id: OTP-8086 Aux Id: seq11333 </p> + </item> + <item> + <p> + The module binary from EEP31 (and EEP9) is implemented.</p> + <p> + Own Id: OTP-8217</p> + </item> + <item> + <p> + New NIF API function <c>enif_make_new_binary</c></p> + <p> + Own Id: OTP-8474</p> + </item> + <item> + <p> + The guard BIF <c>is_boolean/1</c> (introduced in R10B) + has now been included in the lists of BIFs allowed in + guards in the Reference Manual.</p> + <p> + Own Id: OTP-8477</p> + </item> + <item> + <p> + Added function <c>zip:foldl/3</c> to iterate over zip + archives.</p> + <p> + Added functions to create and extract escripts. See + <c>escript:create/2</c> and <c>escript:extract/2</c>.</p> + <p> + The undocumented function <c>escript:foldl/3</c> has been + removed. The same functionality can be achieved with the + more flexible functions <c>escript:extract/2</c> and + <c>zip:foldl/3</c>.</p> + <p> + Record fields has been annotated with type info. Source + files as been adapted to fit within 80 chars and trailing + whitespace has been removed.</p> + <p> + Own Id: OTP-8521</p> + </item> + <item> + <p>A regular expression with many levels of parenthesis + could cause a buffer overflow. That has been corrected. + (Thanks to Michael Santos.)</p> + <p> + Own Id: OTP-8539</p> + </item> + <item> + <p> + <c>erlang:decode_packet(httph_bin,..)</c> could return + corrupt header strings or even crash the VM. This has + been fixed. It only happened on 32-bit VM if the header + name was unknown and between 16 and 20 characters long. + Sockets with simular <c>packet</c> option did not suffer + from this bug.</p> + <p> + Own Id: OTP-8548</p> + </item> + <item> + <p>New NIF features:</p> <list><item> Send messages from + a NIF, or from thread created by NIF, to any local + process (<c>enif_send</c>) </item><item> Store terms + between NIF calls (<c>enif_alloc_env</c>, + <c>enif_make_copy</c>) </item><item> Create binary terms + with user defined memory management + (<c>enif_make_resource_binary</c>) </item></list> <p>And + some incompatible changes made to the API. For more + information see the warning text in <seealso + marker="erl_nif">erl_nif(3)</seealso>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8555</p> + </item> + <item> + <p>If the '<c>fop</c>' program (needed for building PDF + files) cannot not be found, it is now possible to build + the HTML and man pages anyway (there will also be dummy + PDF files with no real content created). (Thanks to + Tuncer Ayaz.)</p> + <p> + Own Id: OTP-8559</p> + </item> + <item> + <p>When defining macros the closing right parenthesis + before the dot is now mandatory.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8562</p> + </item> + <item> + <p>Local and imported functions now override the + auto-imported BIFs when the names clash. The pre R14 + behaviour was that auto-imported BIFs would override + local functions. To avoid that old programs change + behaviour, the following will generate an error:</p> + <list><item><p>Doing a call without explicit module name + to a local function having a name clashing with the name + of an auto-imported BIF that was present (and + auto-imported) before OTP R14A</p></item> + <item><p>Explicitly importing a function having a name + clashing with the name of an autoimported BIF that was + present (and autoimported) before OTP R14A</p></item> + <item><p>Using any form of the old compiler directive + <c>nowarn_bif_clash</c></p></item> </list> <p>If the BIF + was added or auto-imported in OTP R14A or later, + overriding it with an import or a local function will + only result in a warning,</p> <p>To resolve clashes, you + can either use the explicit module name <c>erlang</c> to + call the BIF, or you can remove the auto-import of that + specific BIF by using the new compiler directive + <c>-compile({no_auto_import,[F/A]}).</c>, which makes all + calls to the local or imported function without explicit + module name pass without warnings or errors.</p> <p>The + change makes it possible to add auto-imported BIFs + without breaking or silently changing old code in the + future. However some current code ingeniously utilizing + the old behaviour or the <c>nowarn_bif_clash</c> compiler + directive, might need changing to be accepted by the + compiler.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8579</p> + </item> + <item> + <p> + A bug in re that could cause certain regular expression + matches never to terminate is corrected. (Thanks to + Michael Santos and Gordon Guthrie.)</p> + <p> + Own Id: OTP-8589</p> + </item> + <item> + <p>The erlang:open_port spawn and spawn_executable + directives can include an <c>{env,Env}</c> directive to + set up environment variables for the spawned process. A + bug prevented applications from using <c>{env,Env}</c> to + set an environment variable whose value ended with a + '<c>=</c>' (equal sign) character; the trailing equal + sign was mistaken as an indication that an environment + variable was to be cleared from the environment of the + spawned process. (Thanks to Steve Vinoski.)</p> + <p> + Own Id: OTP-8614</p> + </item> + <item> + <p><c>receive</c> statements that can only read out a + newly created reference are now specially optimized so + that it will execute in constant time regardless of the + number of messages in the receive queue for the process. + That optimization will benefit calls to + <c>gen_server:call()</c>. (See <c>gen:do_call/4</c> for + an example of a receive statement that will be + optimized.)</p> + <p> + Own Id: OTP-8623</p> + </item> + <item> + <p> + The functions file:advise/4 and file:datasync/1 have been + added. (Thanks to Filipe David Manana.)</p> + <p> + Own Id: OTP-8637</p> + </item> + <item> + <p> + New NIF API functions: <c>enif_make_atom_len</c>, + <c>enif_make_existing_atom_len</c>, + <c>enif_make_string_len</c>, <c>enif_get_atom_length</c>, + <c>enif_get_list_length</c>, <c>enif_is_list</c>, + <c>enif_is_tuple</c> (by Tuncer Ayaz)</p> + <p> + Own Id: OTP-8640</p> + </item> + <item> + <p> + Support for using gcc's built-in functions for atomic + memory access has been added. This functionallity will be + used if available and no other native atomic + implementation in ERTS is available.</p> + <p> + Own Id: OTP-8659</p> + </item> + <item> + <p> + The number of spinlocks used when implementing atomic + fall-backs when no native atomic implementation is + available has been increased from 16 to 1024.</p> + <p> + Own Id: OTP-8660</p> + </item> + <item> + <p> + Writer preferred pthread read/write locks has been + enabled on Linux.</p> + <p> + Own Id: OTP-8661</p> + </item> + <item> + <p> + The runtime system will by default bind schedulers to + logical processors using the <c>default_bind</c> bind + type if the amount of schedulers are at least equal to + the amount of logical processors configured, binding of + schedulers is supported, and a CPU topology is available + at startup. </p> + <p> + <em>NOTE:</em> If the Erlang runtime system is the only + operating system process that binds threads to logical + processors, this improves the performance of the runtime + system. However, if other operating system processes (as + for example another Erlang runtime system) also bind + threads to logical processors, there might be a + performance penalty instead. If this is the case you, are + are advised to unbind the schedulers using the <seealso + marker="erl#+sbt">+sbtu</seealso> command line argument, + or by invoking <seealso + marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, + unbound)</seealso>.</p> + <p> + Own Id: OTP-8666</p> + </item> + <item> + <p> + The recently added BIFs erlang:min/2, erlang:max/2 and + erlang:port_command/3 are now auto-imported (as they were + originally intended to be). Due to the recent compiler + change (OTP-8579), the only impact on old code defining + it's own min/2, max/2 or port_command/3 functions will be + a warning, the local functions will still be used. The + warning can be removed by using + -compile({no_auto_import,[min/2,max/2,port_command/3]}). + in the source file.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8669 Aux Id: OTP-8579 </p> + </item> + <item> + <p> + There is a new option 'exclusive' to file:open/2 that + uses the OS O_EXCL flag where supported to open the file + in exclusive mode.</p> + <p> + Own Id: OTP-8670</p> + </item> + <item> + <p> + Now, binary_to_term/2 is auto-imported. This will cause a + compile warning if and only if a module has got a local + function with that name.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8671</p> + </item> + <item> + <p> + Alignment of scheduler data and run queues were adjusted.</p> + <p> + Own Id: OTP-8673</p> + </item> + <item> + <p>Call time breakpoint tracing</p> <list><item>Introduce + a <c>call_time</c> option to + <c>erlang:trace_pattern/3</c>.This option enables call + time breakpoint tracing on code that is executed by + processes with call tracing enabled. Call time tracing + stores the number of calls and the time spent of each + function with this trace pattern enabled. The information + can be retrieved with <c>erlang:trace_info/2</c></item> + <item>Add a scheduler array for BpData. To solve the + issue of multiple schedulers constantly updating the head + pointer to the bp data wheel, each scheduler now has its + own entrypoint to the wheel. This head pointer can be + updated without a locking being taken.</item></list> + <p>Teach call count tracing to use atomics</p> + <list><item>Call count previously used a global lock for + accessing and writing its counter in the breakpoint. This + is now changed to atomics instead.</item> <item>The + change will let call count tracing and cprof to scale + better when increasing the number of + schedulers.</item></list> + <p> + Own Id: OTP-8677</p> + </item> + <item> + <p><c>eprof</c> has been reimplemented with support in + the Erlang virtual machine and is now both faster (i.e. + slows down the code being measured less) and scales much + better. In measurements we saw speed-ups compared to the + old eprof ranging from 6 times (for sequential code that + only uses one scheduler/core) up to 84 times (for + parallel code that uses 8 cores).</p> + <p>Note: The API for the <c>eprof</c> has been cleaned up + and extended. See the documentation.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8706</p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.7.5.1</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -144,7 +634,7 @@ <item> <p>A number of bugs concerning re and unicode are corrected:</p> - <p>re:compile no longer looses unicode option, which also + <p>re:compile no longer loses unicode option, which also fixes bug in re:split.</p> <p>re:replace now handles unicode charlist replacement argument</p> @@ -4716,7 +5206,7 @@ </item> <item> <p>The runtime system with SMP support did not slowly adjust - it's view of time when the system time suddenly changed.</p> + its view of time when the system time suddenly changed.</p> <p>Timeouts could sometimes timeout too early on the runtime system with SMP support.</p> <p>Own Id: OTP-6202</p> |