From f7af5e52d7ada47a38d309aea76e166be27f6288 Mon Sep 17 00:00:00 2001 From: Steve Vinoski Date: Thu, 3 Mar 2011 10:07:15 -0500 Subject: clarify NIF resource object deallocation documentation In the erl_nif documentation, clarify how and when NIF resource objects can be deallocated. Specifically, add focus for the case of calling enif_release_resource immediately after obtaining a resource term from enif_make_resource, since this is likely to be a common approach NIFs use to manage resources. Also fix a couple misspellings in the erl_nif documentation. --- erts/doc/src/erl_nif.xml | 49 +++++++++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 19 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 5987ddbd5e..4bbd4e2a54 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -193,9 +193,9 @@ ok A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of enif_make_resource. The term returned by enif_make_resource - 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 enif_get_resource + is totally opaque in nature. It can be stored and passed between processes + on the same node, but the only real end usage is to pass it back as an argument to a NIF. + The NIF can then call enif_get_resource 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 @@ -212,17 +212,7 @@ ok the garbage collector or enif_release_resource). Resource types are uniquely identified by a supplied name string and the name of the implementing module.

-

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 - library will thereafter be called for the inherited objects and the - 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 there exist resource objects with a destructor - function in the library. -

-

Here is a template example of how to create and return a resource object.

+

Here is a template example of how to create and return a resource object.

ERL_NIF_TERM term; @@ -240,8 +230,13 @@ ok /* resource now only owned by "Erlang" */ } return term; -} - + +

Note that once enif_make_resource creates the term to + return to Erlang, the code can choose to either keep its own + native pointer to the allocated struct and release it later, or + release it immediately and rely solely on the garbage collector + to eventually deallocate the resource object when it collects + the term.

Another usage of resource objects is to create binary terms with user defined memory management. enif_make_resource_binary @@ -251,6 +246,16 @@ ok this can be a binary term consisting of data from a mmap'ed file. The destructor can then do munmap to release the memory region.

+

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 + library will thereafter be called for the inherited objects and the + 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 there exist resource objects with a destructor + function in the library. +

Threads and concurrency

A NIF is thread-safe without any explicit synchronization as @@ -368,7 +373,7 @@ ok environments between NIF calls.

A process independent environment is created by calling enif_alloc_env. It can be - used to store terms beteen NIF calls and to send terms with + used to store terms between NIF calls and to send terms with enif_send. A process independent environment with all its terms is valid until you explicitly invalidates it with enif_free_env @@ -832,8 +837,14 @@ typedef enum { Create an opaque handle to a resource object

Create an opaque handle to a memory managed resource object obtained by enif_alloc_resource. - No ownership transfer is done, the resource object still needs to be released by - enif_release_resource.

+ No ownership transfer is done, as the resource object still needs to be released by + enif_release_resource, + but note that the call to enif_release_resource can occur + immediately after obtaining the term from enif_make_resource, + in which case the resource object will be deallocated when the + term is garbage collected. See the + example of creating and + returning a resource object for more details.

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 term_to_binary -- cgit v1.2.3 From d53be747c945d5e86997e1944446795b271dacb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Fri, 11 Mar 2011 17:34:22 +0100 Subject: Update copyright years --- erts/doc/src/erl.xml | 2 +- erts/doc/src/erl_dist_protocol.xml | 2 +- erts/doc/src/erl_ext_dist.xml | 2 +- erts/doc/src/erlang.xml | 2 +- erts/doc/src/escript.xml | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 1e6e290f6b..a66d273438 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -4,7 +4,7 @@

- 19962010 + 19962011 Ericsson AB. All Rights Reserved. diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 1fe7ac7ecd..6c725fc82d 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -5,7 +5,7 @@
2007 - 2007 + 2011 Ericsson AB, All Rights Reserved diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index c2d58d1ef1..fd2da2cfe3 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -5,7 +5,7 @@
2007 - 2007 + 2011 Ericsson AB, All Rights Reserved diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index c3f06982f5..19f501391f 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index 588508aae6..66e904f64f 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -4,7 +4,7 @@
- 20072010 + 20072011 Ericsson AB. All Rights Reserved. -- cgit v1.2.3 From 91b2e57ea0e3ab794d4b57a12ef10205383525a5 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Mon, 14 Mar 2011 18:18:42 +0100 Subject: Prepare release --- erts/doc/src/notes.xml | 240 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 77181d3407..102fa43c1f 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -30,6 +30,246 @@

This document describes the changes made to the ERTS application.

+
Erts 5.8.3 + +
Fixed Bugs and Malfunctions + + +

+ The scroll wheel now scrolls the werl window on Windows.

+

+ Own Id: OTP-8985

+ + +

+ Some malformed distribution messages could cause VM to + crash, this is now corrected.

+

+ Own Id: OTP-8993

+ + +

+ The OS function getifaddrs() can return NULL in some + address fields for e.g PPP and tunnel devices which + caused the emulator to segfault. This bug has now been + corrected.

+

+ Own Id: OTP-8996

+ + +

+ The expression <<A:0>> would always produce + an empty binary, even if A was not an integer. + Corrected to cause a badarg exception if the type + of A is invalid. (Thanks to Zvi.)

+

+ Own Id: OTP-8997

+ + +

+ A bug that potentially could cause an emulator crash when + deleting an ETS-table has been fixed. A resource leak + when hitting the maximum amount of ETS-tables allowed has + also been fixed.

+

+ Own Id: OTP-8999

+ + +

+ A bug in the exit/2 BIF could potentially cause an + emulator crash.

+

+ Own Id: OTP-9005

+ + +

+ Due to a bug in glibc the runtime system could abort + while trying to destroy a mutex. The runtime system will + now issue a warning instead of aborting.

+

+ Own Id: OTP-9009

+ + +

+ A bug in epmd could create strange behaviour when + listen() calls failed. This is now corrected thanks to + Steve Vinoski.

+

+ Own Id: OTP-9024

+ + +

When setting file_info the win32_driver will now + correctly set access and modified time. Previously these + entities were swapped.

+

+ Own Id: OTP-9046

+ + +

+ Setting scheduler bind type to unbound failed if + binding of schedulers wasn't supported, or if CPU + topology wasn't present. This even though the + documentation stated that it is possible to set the bind + type to unbound.

+

+ Own Id: OTP-9056 Aux Id: Seq11779

+ + +

Two problems were fixed in crash dump: The time left + for timers are now shown as unsigned integers and the + contents of ordered_set ETS tables is no longer + included.

+

+ Own Id: OTP-9057

+ + +

+ The VM could fail to set IP_TOS and SO_PRIORITY in + certain situations, either because sockets were supplied + as open file descriptors, or because SO_PRIORITY by + default was set higher than the user can explicitly set + it to. Those situations are now handled.

+

+ Own Id: OTP-9069

+ + +

+ Wx on MacOS X generated complains on stderr about certain + cocoa functions not beeing called from the "Main thread". + This is now corrected.

+

+ Own Id: OTP-9081

+ + +

+ Fix a couple typos in driver_entry(3) (thanks to Tuncer + Ayaz).

+

+ Own Id: OTP-9085

+ + +

+ Mention that "-detached" implies "-noinput"

+

+ Clarify that specifying "-noinput" is unnecessary if the + "-detached" flag is given. (thanks to Holger Weiß)

+

+ Own Id: OTP-9086

+ + +

+ A potential problem (found by code inspection) when + calling a fun whose code was not loaded has been fixed.

+

+ Own Id: OTP-9095

+ + +

+ The emulator could get into a state where it didn't check + for I/O.

+

+ Own Id: OTP-9105 Aux Id: Seq11798

+ + +

+ Attempting to create binaries exceeding 2Gb (using for + example term_to_binary/1) would crash the emulator + with an attempt to allocate huge amounts of memory. + (Thanks to Jon Meredith.)

+

+ Own Id: OTP-9117

+ + +

+ Fix erlang:hibernate/3 on HiPE enabled emulator (Thanks + to Paul Guyot)

+

+ Own Id: OTP-9125

+ + +
+ + +
Improvements and New Features + + +

From this release, the previously experimental + halfword emulator is now official. It can be enabled by + giving the --enable-halfword-emulator option to + the configure script.

+

The halfword emulator is a 64-bit application, but + uses halfwords (32-bit words) for all data in Erlang + processes, therefore using less memory and being faster + than the standard 64-bit emulator. The total size of all + BEAM code and all process data for all processes is + limited to 4Gb, but ETS tables and off-heap binaries are + only limited by the amount of available memory.

+

+ Own Id: OTP-8941

+ + +

+ 32-bit atomic memory operations have been introduced + internally in the run time system, and are now used where + appropriate. There were previously only atomic memory + operations of word size available. The 32-bit atomic + memory operations slightly reduce memory consumption, and + slightly improve performance on 64-bit runtime systems.

+

+ Own Id: OTP-8974

+ + +

+ Performance enhancements for looking up timer-entries and + removing timers from the wheel.

+

+ Own Id: OTP-8990

+ + +

+ Write accesses to ETS tables have been optimized by + reducing the amount of atomic memory operations needed + during a write access.

+

+ Own Id: OTP-9000

+ + +

+ Strange C coding in the VM made the -D_FORTIFY_SOURCE + option to gcc-4.5 react badly. The code is now cleaned up + so that it's accepted by gcc-4.5.

+

+ Own Id: OTP-9025

+ + +

+ The memory footprint for loaded code has been somewhat + reduced (especially in the 64-bit BEAM machine).

+

+ Own Id: OTP-9030

+ + +

+ The maximum number of allowed arguments for an Erlang + function has been lowered from 256 to 255, so that the + number of arguments can now fit in a byte.

+

+ Own Id: OTP-9049

+ + +

+ Dependency generation for Makefiles has been added to the + compiler and erlc. See the manual pages for + compile and erlc. (Thanks to Jean-Sebastien + Pedron.)

+

+ Own Id: OTP-9065

+ + +
+ +
+
Erts 5.8.2
Fixed Bugs and Malfunctions -- cgit v1.2.3