From fbc7ec5ca3d3c332be007e991a4a68f4b742c8ef Mon Sep 17 00:00:00 2001
From: Rickard Green
Date: Tue, 6 Nov 2012 22:07:53 +0100
Subject: Fix erlang:memory(ets)
---
erts/emulator/beam/erl_db.c | 4 ----
1 file changed, 4 deletions(-)
(limited to 'erts')
diff --git a/erts/emulator/beam/erl_db.c b/erts/emulator/beam/erl_db.c
index 51bdf53823..7409564167 100644
--- a/erts/emulator/beam/erl_db.c
+++ b/erts/emulator/beam/erl_db.c
@@ -250,7 +250,6 @@ free_dbtable(DbTable* tb)
#endif
ASSERT(is_immed(tb->common.heir_data));
erts_db_free(ERTS_ALC_T_DB_TABLE, tb, (void *) tb, sizeof(DbTable));
- ERTS_ETS_MISC_MEM_ADD(-sizeof(DbTable));
ERTS_SMP_MEMORY_BARRIER;
}
@@ -1443,7 +1442,6 @@ BIF_RETTYPE ets_new_2(BIF_ALIST_2)
erts_smp_atomic_init_nob(&init_tb.common.memory_size, 0);
tb = (DbTable*) erts_db_alloc(ERTS_ALC_T_DB_TABLE,
&init_tb, sizeof(DbTable));
- ERTS_ETS_MISC_MEM_ADD(sizeof(DbTable));
erts_smp_atomic_init_nob(&tb->common.memory_size,
erts_smp_atomic_read_nob(&init_tb.common.memory_size));
}
@@ -2888,7 +2886,6 @@ void init_db(void)
meta_pid_to_tab = (DbTable*) erts_db_alloc(ERTS_ALC_T_DB_TABLE,
&init_tb,
sizeof(DbTable));
- ERTS_ETS_MISC_MEM_ADD(sizeof(DbTable));
erts_smp_atomic_init_nob(&meta_pid_to_tab->common.memory_size,
erts_smp_atomic_read_nob(&init_tb.common.memory_size));
@@ -2920,7 +2917,6 @@ void init_db(void)
meta_pid_to_fixed_tab = (DbTable*) erts_db_alloc(ERTS_ALC_T_DB_TABLE,
&init_tb,
sizeof(DbTable));
- ERTS_ETS_MISC_MEM_ADD(sizeof(DbTable));
erts_smp_atomic_init_nob(&meta_pid_to_fixed_tab->common.memory_size,
erts_smp_atomic_read_nob(&init_tb.common.memory_size));
--
cgit v1.2.3
From 8a273f85e26ad7ae533b0d9e5f429be34ee8a537 Mon Sep 17 00:00:00 2001
From: Rickard Green
Date: Tue, 6 Nov 2012 00:42:49 +0100
Subject: Add clearer warnings about misuse of NIF and driver functionality
---
erts/doc/src/driver_entry.xml | 23 ++++++++++
erts/doc/src/erl_driver.xml | 57 ++++++++++++++++++++-----
erts/doc/src/erl_nif.xml | 97 ++++++++++++++++++++++++++++++-------------
3 files changed, 138 insertions(+), 39 deletions(-)
(limited to 'erts')
diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml
index a2efdf3ebc..929c485c36 100644
--- a/erts/doc/src/driver_entry.xml
+++ b/erts/doc/src/driver_entry.xml
@@ -34,6 +34,29 @@
driver_entry
The driver-entry structure used by erlang drivers.
+
+ Use this functionality with extreme care!
+ A driver callback is executed as a direct extension of the
+ native code of the VM. Execution is not made in a safe environment.
+ The VM can not provide the same services as provided when
+ executing Erlang code, such as preemptive scheduling or memory
+ protection. If the driver callback function doesn't behave well,
+ the whole VM will misbehave.
+
+ A driver callback that crash will crash the whole VM.
+ An erroneously implemented driver callback might cause
+ a VM internal state inconsistency which may cause a crash of the VM,
+ or miscellaneous misbehaviors of the VM at any point after the call
+ to the driver callback.
+ A driver callback that do
+ lengthy work
+ before returning will degrade responsiveness of the VM,
+ and may cause miscellaneous strange behaviors. Such strange behaviors
+ include, but are not limited to, extreme memory usage, and bad load
+ balancing between schedulers. Strange behaviors that might occur due
+ to lengthy work may also vary between OTP releases.
+
+
As of erts version 5.9 (OTP release R15B) the driver interface
has been changed with larger types for the callbacks
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index 187c263b60..e16fd744c0 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -34,6 +34,32 @@
erl_driver
API functions for an Erlang driver
+ An Erlang driver is a library containing a set of native driver
+ callback functions that the Erlang VM calls when certain
+ events occur. There may be multiple instances of a driver, each
+ instance is associated with an Erlang port.
+
+ Use this functionality with extreme care!
+ A driver callback is executed as a direct extension of the
+ native code of the VM. Execution is not made in a safe environment.
+ The VM can not provide the same services as provided when
+ executing Erlang code, such as preemptive scheduling or memory
+ protection. If the driver callback function doesn't behave well,
+ the whole VM will misbehave.
+
+ A driver callback that crash will crash the whole VM.
+ An erroneously implemented driver callback might cause
+ a VM internal state inconsistency which may cause a crash of the VM,
+ or miscellaneous misbehaviors of the VM at any point after the call
+ to the driver callback.
+ A driver callback that do lengthy
+ work before returning will degrade responsiveness of the VM,
+ and may cause miscellaneous strange behaviors. Such strange behaviors
+ include, but are not limited to, extreme memory usage, and bad load
+ balancing between schedulers. Strange behaviors that might occur due
+ to lengthy work may also vary between OTP releases.
+
+
As of erts version 5.5.3 the driver interface has been extended
(see extended marker).
The extended interface introduce
@@ -53,16 +79,12 @@
The driver calls back to the emulator, using the API
functions declared in erl_driver.h. They are used for
outputting data from the driver, using timers, etc.
- A driver is a library with a set of function that the emulator
- calls, in response to Erlang functions and message
- sending. There may be multiple instances of a driver, each
- instance is connected to an Erlang port. Every port has a port
- owner process. Communication with the port is normally done
- through the port owner process.
- Most of the functions take the port handle as an
- argument. This identifies the driver instance. Note that this
- port handle must be stored by the driver, it is not given when
- the driver is called from the emulator (see
+
Each driver instance is associated with a port. Every port
+ has a port owner process. Communication with the port is normally
+ done through the port owner process. Most of the functions take
+ the port handle as an argument. This identifies the driver
+ instance. Note that this port handle must be stored by the driver,
+ it is not given when the driver is called from the emulator (see
driver_entry).
Some of the functions take a parameter of type
ErlDrvBinary, a driver binary. It should be both
@@ -129,6 +151,21 @@
are only thread safe when used in a runtime
system with SMP support.
+
+ As mentioned in the warning text at
+ the beginning of this document it is of vital importance that a driver callback
+ does return relatively fast. It is hard to give an exact maximum amount
+ of time that a driver callback is allowed to work, but as a rule of thumb
+ a well behaving driver callback should return before a millisecond has
+ passed. This can be achieved using different approaches.
+ If you have full control over the code that are to execute in the driver
+ callback, the best approach is to divide the work into multiple chunks of
+ work and trigger multiple calls to the
+ timeout callback using
+ zero timeouts. This might, however, not always be possible, e.g. when
+ calling third party libraries. In this case you typically want to dispatch
+ the work to another thread. Information about thread primitives can be
+ found below.
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index f484e9eaf7..f00f7b9f46 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -34,30 +34,6 @@
erl_nif
API functions for an Erlang NIF library
- The NIF concept is officially supported from R14B. NIF source code
- written for earlier experimental versions might need adaption to run on R14B.
- No incompatible changes between R14B and R14A.
- Incompatible changes between R14A and R13B04:
-
- - Environment argument removed for enif_alloc,
- enif_realloc, enif_free, enif_alloc_binary,
- enif_realloc_binary, enif_release_binary,
- enif_alloc_resource, enif_release_resource,
- enif_is_identical and enif_compare.
- - Character encoding argument added to enif_get_atom
- and enif_make_existing_atom.
- - Module argument added to enif_open_resource_type
- while changing name spaces of resource types from global to module local.
-
- Incompatible changes between R13B04 and R13B03:
-
- - The function prototypes of the NIFs have changed to expect argc and argv
- arguments. The arity of a NIF is by that no longer limited to 3.
- - enif_get_data renamed as enif_priv_data.
- - enif_make_string got a third argument for character encoding.
-
-
-
A NIF library contains native implementation of some functions
of an Erlang module. The native implemented functions (NIFs) are
called like any other functions without any difference to the
@@ -67,6 +43,57 @@
is to throw an exception. But it can also be used as a fallback
implementation if the NIF library is not implemented for some
architecture.
+
+ Use this functionality with extreme care!
+ A native function is executed as a direct extension of the
+ native code of the VM. Execution is not made in a safe environment.
+ The VM can not provide the same services as provided when
+ executing Erlang code, such as preemptive scheduling or memory
+ protection. If the native function doesn't behave well, the whole
+ VM will misbehave.
+
+ A native function that crash will crash the whole VM.
+ An erroneously implemented native function might cause
+ a VM internal state inconsistency which may cause a crash of the VM,
+ or miscellaneous misbehaviors of the VM at any point after the call
+ to the native function.
+ A native function that do lengthy
+ work before returning will degrade responsiveness of the VM,
+ and may cause miscellaneous strange behaviors. Such strange behaviors
+ include, but are not limited to, extreme memory usage, and bad load
+ balancing between schedulers. Strange behaviors that might occur due
+ to lengthy work may also vary between OTP releases.
+
+
+
+ The NIF concept is officially supported from R14B. NIF source code
+ written for earlier experimental versions might need adaption to run on R14B
+ or later versions:
+
+ - No incompatible changes between R14B and R14A.
+ - Incompatible changes between R14A and R13B04:
+
+ - Environment argument removed for enif_alloc,
+ enif_realloc, enif_free, enif_alloc_binary,
+ enif_realloc_binary, enif_release_binary,
+ enif_alloc_resource, enif_release_resource,
+ enif_is_identical and enif_compare.
+ - Character encoding argument added to enif_get_atom
+ and enif_make_existing_atom.
+ - Module argument added to enif_open_resource_type
+ while changing name spaces of resource types from global to module local.
+
+
+ - Incompatible changes between R13B04 and R13B03:
+
+ - The function prototypes of the NIFs have changed to expect argc and argv
+ arguments. The arity of a NIF is by that no longer limited to 3.
+ - enif_get_data renamed as enif_priv_data.
+ - enif_make_string got a third argument for character encoding.
+
+
+
+
A minimal example of a NIF library can look like this:
@@ -136,7 +163,23 @@ ok
then retrieved by calling enif_priv_data.
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.
+ by the code server.
+
+
+ As mentioned in the warning text at
+ the beginning of this document it is of vital importance that a native function
+ does return relatively fast. It is hard to give an exact maximum amount
+ of time that a native function is allowed to work, but as a rule of thumb
+ a well behaving native function should return to its caller before a
+ millisecond has passed. This can be achieved using different approaches.
+ If you have full control over the code that are to execute in the native
+ function, the best approach is to divide the work into multiple chunks of
+ work and call the native function multiple times. This might, however,
+ not always be possible, e.g. when calling third party libraries. In this
+ case you typically want to dispatch the work to another thread, return
+ from the native function, and wait for the result. The thread can send
+ the result back to the calling thread using message passing. Information
+ about thread primitives can be found below.
FUNCTIONALITY
@@ -266,10 +309,6 @@ ok
mutable.
The library initialization callbacks load, reload and
upgrade are all thread-safe even for shared state data.
- Avoid doing lengthy work in NIF calls as that may degrade the
- responsiveness of the VM. NIFs are called directly by the same scheduler
- thread that executed the calling Erlang code. The calling scheduler will thus
- be blocked from doing any other work until the NIF returns.
--
cgit v1.2.3