From d281213a4a04a61910a6c451d8f5c86e61416bb2 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Mon, 11 Jul 2016 17:05:31 +0200 Subject: erts: Move all functions in docs to be in alphabetical order This commit only changes the order of functions and does some other rearrangements to that the diff with the next commit will be easier to follow. No content or XML tags are changed. --- erts/doc/src/erl_driver.xml | 3173 ++++++++++++++++++++++--------------------- erts/doc/src/erl_nif.xml | 890 ++++++++---- erts/doc/src/erl_tracer.xml | 263 ++-- erts/doc/src/erlang.xml | 476 ++++--- erts/doc/src/zlib.xml | 429 +++--- 5 files changed, 2862 insertions(+), 2369 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 82215ead46..d8116d4650 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -893,358 +893,339 @@ typedef struct ErlIOVec { - voiddriver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size) - Get information about the Erlang runtime system + voidadd_driver_entry(ErlDrvEntry *de) + Add a driver entry - -

This function will write information about the Erlang runtime - system into the - ErlDrvSysInfo - structure referred to by the first argument. The second - argument should be the size of the - ErlDrvSysInfo - structure, i.e., sizeof(ErlDrvSysInfo).

-

See the documentation of the - ErlDrvSysInfo - structure for information about specific fields.

+ +

This function adds a driver entry to the list of drivers + known by Erlang. The init function of the de + parameter is called.

+ +

To use this function for adding drivers residing in + dynamically loaded code is dangerous. If the driver code + for the added driver resides in the same dynamically + loaded module (i.e. .so file) as a normal + dynamically loaded driver (loaded with the erl_ddll + interface), the caller should call driver_lock_driver before + adding driver entries.

+

Use of this function is generally deprecated.

+ + - intdriver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len) - Send data from driver to port owner + void *driver_alloc(ErlDrvSizeT size) + Allocate memory - -

The driver_output function is used to send data from - the driver up to the emulator. The data will be received as - terms or binary data, depending on how the driver port was - opened.

-

The data is queued in the port owner process' message - queue. Note that this does not yield to the emulator. (Since - the driver and the emulator run in the same thread.)

-

The parameter buf points to the data to send, and - len is the number of bytes.

-

The return value for all output functions is 0. (Unless the - driver is used for distribution, in which case it can fail - and return -1. For normal use, the output function always - returns 0.)

+ +

This function allocates a memory block of the size specified + in size, and returns it. This only fails on out of + memory, in that case NULL is returned. (This is most + often a wrapper for malloc).

+

Memory allocated must be explicitly freed with a corresponding + call to driver_free (unless otherwise stated).

+

This function is thread-safe.

 + - intdriver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len) - Send data and binary data to port owner + ErlDrvBinary *driver_alloc_binary(ErlDrvSizeT size) + Allocate a driver binary - -

The driver_output2 function first sends hbuf - (length in hlen) data as a list, regardless of port - settings. Then buf is sent as a binary or list. - E.g. if hlen is 3 then the port owner process will - receive [H1, H2, H3 | T].

-

The point of sending data as a list header, is to facilitate - matching on the data received.

-

The return value is 0 for normal use.

+ +

This function allocates a driver binary with a memory block + of at least size bytes, and returns a pointer to it, + or NULL on failure (out of memory). When a driver binary has + been sent to the emulator, it must not be altered. Every + allocated binary should be freed by a corresponding call to + driver_free_binary (unless otherwise stated).

+

Note that a driver binary has an internal reference counter, + this means that calling driver_free_binary it may not + actually dispose of it. If it's sent to the emulator, it may + be referenced there.

+

The driver binary has a field, orig_bytes, which + marks the start of the data in the binary.

+

This function is thread-safe.

 + - intdriver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len) - Send data from a driver binary to port owner + longdriver_async (ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*)) + Perform an asynchronous call within a driver - -

This function sends data to port owner process from a - driver binary, it has a header buffer (hbuf - and hlen) just like driver_output2. The - hbuf parameter can be NULL.

-

The parameter offset is an offset into the binary and - len is the number of bytes to send.

-

Driver binaries are created with driver_alloc_binary.

-

The data in the header is sent as a list and the binary as - an Erlang binary in the tail of the list.

-

E.g. if hlen is 2, then the port owner process will - receive >]]]>.

-

The return value is 0 for normal use.

-

Note that, using the binary syntax in Erlang, the driver - application can match the header directly from the binary, - so the header can be put in the binary, and hlen can be set - to 0.

+ +

This function performs an asynchronous call. The function + async_invoke is invoked in a thread separate from the + emulator thread. This enables the driver to perform + time-consuming, blocking operations without blocking the + emulator.

+

The async thread pool size can be set with the + +A + command line argument of erl(1). + If no async thread pool is available, the call is made + synchronously in the thread calling driver_async(). The + current number of async threads in the async thread pool can be + retrieved via + driver_system_info().

+

If there is a thread pool available, a thread will be + used. If the key argument is null, the threads from the + pool are used in a round-robin way, each call to + driver_async uses the next thread in the pool. With the + key argument set, this behaviour is changed. The two + same values of *key always get the same thread.

+

To make sure that a driver instance always uses the same + thread, the following call can be used:

+

+ +

It is enough to initialize myKey once for each + driver instance.

+

If a thread is already working, the calls will be + queued up and executed in order. Using the same thread for + each driver instance ensures that the calls will be made in + sequence.

+

The async_data is the argument to the functions + async_invoke and async_free. It's typically a + pointer to a structure that contains a pipe or event that + can be used to signal that the async operation completed. + The data should be freed in async_free.

+

When the async operation is done, ready_async driver + entry function is called. If ready_async is null in + the driver entry, the async_free function is called + instead.

+

The return value is -1 if the driver_async call + fails.

+ +

As of erts version 5.5.4.3 the default stack size for + threads in the async-thread pool is 16 kilowords, + i.e., 64 kilobyte on 32-bit architectures. + This small default size has been chosen since the + amount of async-threads might be quite large. The + default stack size is enough for drivers delivered + with Erlang/OTP, but might not be sufficiently large + for other dynamically linked in drivers that use the + driver_async() functionality. A suggested stack size + for threads in the async-thread pool can be configured + via the + +a + command line argument of + erl(1).

+ - - intdriver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip) - Send vectorized data to port owner + + unsigned intdriver_async_port_key (ErlDrvPort port) + Calculate an async key from an ErlDrvPort - -

This function sends data from an IO vector, ev, to - the port owner process. It has a header buffer (hbuf - and hlen), just like driver_output2.

-

The skip parameter is a number of bytes to skip of - the ev vector from the head.

-

You get vectors of ErlIOVec type from the driver - queue (see below), and the outputv driver entry - function. You can also make them yourself, if you want to - send several ErlDrvBinary buffers at once. Often - it is faster to use driver_output or - driver_output_binary.

-

E.g. if hlen is 2 and ev points to an array of - three binaries, the port owner process will receive >, <> | <>]]]>.

-

The return value is 0 for normal use.

-

The comment for driver_output_binary applies for - driver_outputv too.

+ +

This function calculates a key for later use in driver_async(). The keys are + evenly distributed so that a fair mapping between port id's + and async thread id's is achieved.

+ +

Before OTP-R16, the actual port id could be used as a key + with proper casting, but after the rewrite of the port + subsystem, this is no longer the case. With this function, you + can achieve the same distribution based on port id's as before + OTP-R16.

+ + - ErlDrvSizeTdriver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len) - Collect data segments into a buffer + longdriver_binary_dec_refc(ErlDrvBinary *bin) + Decrement the reference count of a driver binary - -

This function collects several segments of data, referenced - by ev, by copying them in order to the buffer - buf, of the size len.

-

If the data is to be sent from the driver to the port owner - process, it is faster to use driver_outputv.

-

The return value is the space left in the buffer, i.e. if - the ev contains less than len bytes it's the - difference, and if ev contains len bytes or - more, it's 0. This is faster if there is more than one header byte, - since the binary syntax can construct integers directly from - the binary.

+ +

Decrements the reference count on bin and returns + the reference count reached after the decrement.

+

This function is only thread-safe when the emulator with SMP + support is used.

+ +

You should normally decrement the reference count of a + driver binary by calling + driver_free_binary(). + driver_binary_dec_refc() does not free + the binary if the reference count reaches zero. Only + use driver_binary_dec_refc() when you are sure + not to reach a reference count of zero.

+ + - intdriver_set_timer(ErlDrvPort port, unsigned long time) - Set a timer to call the driver + longdriver_binary_get_refc(ErlDrvBinary *bin) + Get the reference count of a driver binary - -

This function sets a timer on the driver, which will count - down and call the driver when it is timed out. The - time parameter is the time in milliseconds before the - timer expires.

-

When the timer reaches 0 and expires, the driver entry - function timeout is called.

-

Note that there is only one timer on each driver instance; - setting a new timer will replace an older one.

-

Return value is 0 (-1 only when the timeout driver - function is NULL).

+ +

Returns current reference count on bin.

+

This function is only thread-safe when the emulator with SMP + support is used.

 + - intdriver_cancel_timer(ErlDrvPort port) - Cancel a previously set timer - - -

This function cancels a timer set with - driver_set_timer.

-

The return value is 0.

- - - - intdriver_read_timer(ErlDrvPort port, unsigned long *time_left) - Read the time left before timeout + longdriver_binary_inc_refc(ErlDrvBinary *bin) + Increment the reference count of a driver binary - -

This function reads the current time of a timer, and places - the result in time_left. This is the time in - milliseconds, before the timeout will occur.

-

The return value is 0.

+ +

Increments the reference count on bin and returns + the reference count reached after the increment.

+

This function is only thread-safe when the emulator with SMP + support is used.

 + - intdriver_get_now(ErlDrvNowData *now) - Read a system timestamp + ErlDrvTermDatadriver_caller(ErlDrvPort port) + Return the process making the driver call - -

This function is deprecated! Do not use it! - Use erl_drv_monotonic_time() - (perhaps in combination with - erl_drv_time_offset()) - instead.

 -

This function reads a timestamp into the memory pointed to by - the parameter now. See the description of ErlDrvNowData for - specification of its fields.

-

The return value is 0 unless the now pointer is not - valid, in which case it is < 0.

+ +

This function returns the process id of the process that + made the current call to the driver. The process id can be + used with driver_send_term to send back data to the + caller. driver_caller() only returns valid data + when currently executing in one of the following driver + callbacks:

+ + start + Called from open_port/2. + output + Called from erlang:send/2, and + erlang:port_command/2 + outputv + Called from erlang:send/2, and + erlang:port_command/2 + control + Called from erlang:port_control/3 + call + Called from erlang:port_call/3 + +

Note that this function is not thread-safe, not + even when the emulator with SMP support is used.

 + - intdriver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on) - Provide an event for having the emulator call the driver + intdriver_cancel_timer(ErlDrvPort port) + Cancel a previously set timer - -

This function is used by drivers to provide the emulator with - events to check for. This enables the emulator to call the driver - when something has happened asynchronously.

-

The event argument identifies an OS-specific event object. - On Unix systems, the functions select/poll are used. The - event object must be a socket or pipe (or other object that - select/poll can use). - On windows, the Win32 API function WaitForMultipleObjects - is used. This places other restrictions on the event object. - Refer to the Win32 SDK documentation.

-

The on parameter should be 1 for setting events - and 0 for clearing them.

-

The mode argument is a bitwise-or combination of - ERL_DRV_READ, ERL_DRV_WRITE and ERL_DRV_USE. - The first two specify whether to wait for read events and/or write - events. A fired read event will call - ready_input - while a fired write event will call - ready_output. -

- -

Some OS (Windows) do not differentiate between read and write events. - The call-back for a fired event then only depends on the value of mode.

- -

ERL_DRV_USE specifies if we are using the event object or if we want to close it. - On an emulator with SMP support, it is not safe to clear all events - and then close the event object after driver_select has - returned. Another thread may still be using the event object - internally. To safely close an event object call - driver_select with ERL_DRV_USE and on==0. That - will clear all events and then call - stop_select - when it is safe to close the event object. - ERL_DRV_USE should be set together with the first event - for an event object. It is harmless to set ERL_DRV_USE - even though it already has been done. Clearing all events but keeping - ERL_DRV_USE set will indicate that we are using the event - object and probably will set events for it again.

- -

ERL_DRV_USE was added in OTP release R13. Old drivers will still work - as before. But it is recommended to update them to use ERL_DRV_USE and - stop_select to make sure that event objects are closed in a safe way.

- -

The return value is 0 (failure, -1, only if the - ready_input/ready_output is - NULL).

+ +

This function cancels a timer set with + driver_set_timer.

+

The return value is 0.

 + - void *driver_alloc(ErlDrvSizeT size) - Allocate memory + intdriver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2) + Compare two monitors - -

This function allocates a memory block of the size specified - in size, and returns it. This only fails on out of - memory, in that case NULL is returned. (This is most - often a wrapper for malloc).

-

Memory allocated must be explicitly freed with a corresponding - call to driver_free (unless otherwise stated).

-

This function is thread-safe.

+ +

This function is used to compare two ErlDrvMonitors. It + can also be used to imply some artificial order on monitors, + for whatever reason.

+

The function returns 0 if monitor1 and + monitor2 are equal, < 0 if monitor1 is less + than monitor2 and > 0 if monitor1 is greater + than monitor2.

 + - void *driver_realloc(void *ptr, ErlDrvSizeT size) - Resize an allocated memory block + ErlDrvTermDatadriver_connected(ErlDrvPort port) + Return the port owner process - -

This function resizes a memory block, either in place, or by - allocating a new block, copying the data and freeing the old - block. A pointer is returned to the reallocated memory. On - failure (out of memory), NULL is returned. (This is - most often a wrapper for realloc.)

-

This function is thread-safe.

+ +

This function returns the port owner process.

+

Note that this function is not thread-safe, not + even when the emulator with SMP support is used.

 + - voiddriver_free(void *ptr) - Free an allocated memory block + ErlDrvPortdriver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data) + Create a new port (driver instance) - -

This function frees the memory pointed to by ptr. The - memory should have been allocated with - driver_alloc. All allocated memory should be - deallocated, just once. There is no garbage collection in - drivers.

-

This function is thread-safe.

+

This function creates a new port executing the same driver + code as the port creating the new port. + A short description of the arguments:

+ + port + The port handle of the port (driver instance) creating + the new port. + owner_pid + The process id of the Erlang process which will be + owner of the new port. This process will be linked + to the new port. You usually want to use + driver_caller(port) as owner_pid. + name + The port name of the new port. You usually want to + use the same port name as the driver name + (driver_name + field of the + driver_entry). + drv_data + The driver defined handle that will be passed in subsequent + calls to driver call-backs. Note, that the + driver start call-back + will not be called for this new driver instance. + The driver defined handle is normally created in the + driver start call-back + when a port is created via + erlang:open_port/2. + +

The caller of driver_create_port() is allowed to + manipulate the newly created port when driver_create_port() + has returned. When + port level locking + is used, the creating port is, however, only allowed to + manipulate the newly created port until the current driver + call-back that was called by the emulator returns.

+ +

When + port level locking + is used, the creating port is only allowed to manipulate + the newly created port until the current driver call-back + returns.

+ + - ErlDrvBinary *driver_alloc_binary(ErlDrvSizeT size) - Allocate a driver binary + intdriver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor) + Stop monitoring a process from a driver - -

This function allocates a driver binary with a memory block - of at least size bytes, and returns a pointer to it, - or NULL on failure (out of memory). When a driver binary has - been sent to the emulator, it must not be altered. Every - allocated binary should be freed by a corresponding call to - driver_free_binary (unless otherwise stated).

-

Note that a driver binary has an internal reference counter, - this means that calling driver_free_binary it may not - actually dispose of it. If it's sent to the emulator, it may - be referenced there.

-

The driver binary has a field, orig_bytes, which - marks the start of the data in the binary.

-

This function is thread-safe.

+ +

This function cancels a monitor created earlier.

+

The function returns 0 if a monitor was removed and > 0 + if the monitor did no longer exist.

 + - ErlDrvBinary *driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size) - Resize a driver binary + ErlDrvSizeTdriver_deq(ErlDrvPort port, ErlDrvSizeT size) + Dequeue data from the head of the driver queue - -

This function resizes a driver binary, while keeping the - data. The resized driver binary is returned. On failure (out - of memory), NULL is returned.

-

This function is only thread-safe when the emulator with SMP - support is used.

+ +

This function dequeues data by moving the head pointer + forward in the driver queue by size bytes. The data + in the queue will be deallocated.

+

The return value is the number of bytes remaining in the queue + or -1 on failure.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

 + - voiddriver_free_binary(ErlDrvBinary *bin) - Free a driver binary - - -

This function frees a driver binary bin, allocated - previously with driver_alloc_binary. Since binaries - in Erlang are reference counted, the binary may still be - around.

-

This function is only thread-safe when the emulator with SMP - support is used.

- - - - longdriver_binary_get_refc(ErlDrvBinary *bin) - Get the reference count of a driver binary - - -

Returns current reference count on bin.

-

This function is only thread-safe when the emulator with SMP - support is used.

- - - - longdriver_binary_inc_refc(ErlDrvBinary *bin) - Increment the reference count of a driver binary - - -

Increments the reference count on bin and returns - the reference count reached after the increment.

-

This function is only thread-safe when the emulator with SMP - support is used.

- - - - longdriver_binary_dec_refc(ErlDrvBinary *bin) - Decrement the reference count of a driver binary - - -

Decrements the reference count on bin and returns - the reference count reached after the decrement.

-

This function is only thread-safe when the emulator with SMP - support is used.

- -

You should normally decrement the reference count of a - driver binary by calling - driver_free_binary(). - driver_binary_dec_refc() does not free - the binary if the reference count reaches zero. Only - use driver_binary_dec_refc() when you are sure - not to reach a reference count of zero.

- - - - - intdriver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len) - Enqueue data in the driver queue + intdriver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len) + Enqueue data in the driver queue

This function enqueues data in the driver queue. The data in @@ -1266,50 +1247,7 @@ typedef struct ErlIOVec { thread during the call.

 - - intdriver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len) - Push data at the head of the driver queue - - -

This function puts data at the head of the driver queue. The - data in buf is copied (len bytes) and placed - at the beginning of the queue.

-

The return value is 0.

-

This function can be called from an arbitrary thread if a - port data lock - associated with the port is locked by the calling - thread during the call.

- - - - ErlDrvSizeTdriver_deq(ErlDrvPort port, ErlDrvSizeT size) - Dequeue data from the head of the driver queue - - -

This function dequeues data by moving the head pointer - forward in the driver queue by size bytes. The data - in the queue will be deallocated.

-

The return value is the number of bytes remaining in the queue - or -1 on failure.

-

This function can be called from an arbitrary thread if a - port data lock - associated with the port is locked by the calling - thread during the call.

- - - - ErlDrvSizeTdriver_sizeq(ErlDrvPort port) - Return the size of the driver queue - - -

This function returns the number of bytes currently in the - driver queue.

-

This function can be called from an arbitrary thread if a - port data lock - associated with the port is locked by the calling - thread during the call.

- - + intdriver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) Enqueue binary in the driver queue @@ -1327,64 +1265,7 @@ typedef struct ErlIOVec {

The return value is 0.

 - - intdriver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) - Push binary at the head of the driver queue - - -

This function puts data in the binary bin, at - offset with length len at the head of the - driver queue. It is most often faster than - driver_pushq, because the data doesn't have to be - copied.

-

This function can be called from an arbitrary thread if a - port data lock - associated with the port is locked by the calling - thread during the call.

-

The return value is 0.

- - - - ErlDrvSizeTdriver_peekqv(ErlDrvPort port, ErlIOVec *ev) - Get the driver queue as an IO vector - - -

- This function retrieves the driver queue into a supplied - ErlIOVec ev. It also returns the queue size. - This is one of two ways to get data out of the queue. -

-

- If ev is NULL all ones i.e. -1 type cast to - ErlDrvSizeT is returned. -

-

Nothing is removed from the queue by this function, that must be done - with driver_deq.

-

This function can be called from an arbitrary thread if a - port data lock - associated with the port is locked by the calling - thread during the call.

- - - - SysIOVec *driver_peekq(ErlDrvPort port, int *vlen) - Get the driver queue as a vector - - -

This function retrieves the driver queue as a pointer to an - array of SysIOVecs. It also returns the number of - elements in vlen. This is one of two ways to get data - out of the queue.

-

Nothing is removed from the queue by this function, that must be done - with driver_deq.

-

The returned array is suitable to use with the Unix system - call writev.

-

This function can be called from an arbitrary thread if a - port data lock - associated with the port is locked by the calling - thread during the call.

- - + intdriver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip) Enqueue vector in the driver queue @@ -1401,91 +1282,143 @@ typedef struct ErlIOVec { thread during the call.

 + - intdriver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip) - Push vector at the head of the driver queue + intdriver_failure_atom(ErlDrvPort port, char *string) + intdriver_failure_posix(ErlDrvPort port, int error) + intdriver_failure(ErlDrvPort port, int error) + Fail with error - -

This function puts the data in ev, skipping the first - skip bytes of it, at the head of the driver queue. - It is faster than driver_pushq, because the data - doesn't have to be copied.

+ + + +

These functions signal to Erlang that the driver has + encountered an error and should be closed. The port is + closed and the tuple {'EXIT', error, Err}, is sent to + the port owner process, where error is an error atom + (driver_failure_atom and + driver_failure_posix), or an integer + (driver_failure).

+

The driver should fail only when in severe error situations, + when the driver cannot possibly keep open, for instance + buffer allocation gets out of memory. For normal errors + it is more appropriate to send error codes with + driver_output.

The return value is 0.

-

This function can be called from an arbitrary thread if a - port data lock - associated with the port is locked by the calling - thread during the call.

 + - ErlDrvPDLdriver_pdl_create(ErlDrvPort port) - Create a port data lock + intdriver_failure_eof(ErlDrvPort port) + Fail with EOF - -

This function creates a port data lock associated with - the port. NOTE: Once a port data lock has - been created, it has to be locked during all operations - on the driver queue of the port.

-

On success a newly created port data lock is returned. On - failure NULL is returned. driver_pdl_create() will - fail if port is invalid or if a port data lock already has - been associated with the port.

+ +

This function signals to erlang that the driver has + encountered an EOF and should be closed, unless the port was + opened with the eof option, in that case eof is sent + to the port. Otherwise, the port is closed and an + 'EXIT' message is sent to the port owner process.

+

The return value is 0.

 + - voiddriver_pdl_lock(ErlDrvPDL pdl) - Lock port data lock + voiddriver_free(void *ptr) + Free an allocated memory block - -

This function locks the port data lock passed as argument - (pdl).

+ +

This function frees the memory pointed to by ptr. The + memory should have been allocated with + driver_alloc. All allocated memory should be + deallocated, just once. There is no garbage collection in + drivers.

This function is thread-safe.

 + - voiddriver_pdl_unlock(ErlDrvPDL pdl) - Unlock port data lock + voiddriver_free_binary(ErlDrvBinary *bin) + Free a driver binary - -

This function unlocks the port data lock passed as argument - (pdl).

-

This function is thread-safe.

+ +

This function frees a driver binary bin, allocated + previously with driver_alloc_binary. Since binaries + in Erlang are reference counted, the binary may still be + around.

+

This function is only thread-safe when the emulator with SMP + support is used.

 + - longdriver_pdl_get_refc(ErlDrvPDL pdl) - + ErlDrvTermDatadriver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor) + Retrieve the process id from a monitor - -

This function returns the current reference count of - the port data lock passed as argument (pdl).

-

This function is thread-safe.

+ +

The function returns the process id associated with a living + monitor. It can be used in the process_exit call-back to + get the process identification for the exiting process.

+

The function returns driver_term_nil if the monitor + no longer exists.

 + - longdriver_pdl_inc_refc(ErlDrvPDL pdl) - + intdriver_get_now(ErlDrvNowData *now) + Read a system timestamp - -

This function increments the reference count of - the port data lock passed as argument (pdl).

-

The current reference count after the increment has - been performed is returned.

-

This function is thread-safe.

+ +

This function is deprecated! Do not use it! + Use erl_drv_monotonic_time() + (perhaps in combination with + erl_drv_time_offset()) + instead.

 +

This function reads a timestamp into the memory pointed to by + the parameter now. See the description of ErlDrvNowData for + specification of its fields.

+

The return value is 0 unless the now pointer is not + valid, in which case it is < 0.

+ - longdriver_pdl_dec_refc(ErlDrvPDL pdl) - + intdriver_lock_driver(ErlDrvPort port) + Make sure the driver is never unloaded - -

This function decrements the reference count of - the port data lock passed as argument (pdl).

-

The current reference count after the decrement has - been performed is returned.

-

This function is thread-safe.

+ +

This function locks the driver used by the port port + in memory for the rest of the emulator process' + lifetime. After this call, the driver behaves as one of Erlang's + statically linked in drivers.

+ + + + + ErlDrvTermDatadriver_mk_atom(char* string) + Make an atom from a name + + +

This function returns an atom given a name + string. The atom is created and won't change, so the + return value may be saved and reused, which is faster than + looking up the atom several times.

+

Note that this function is not thread-safe, not + even when the emulator with SMP support is used.

+ + + + + ErlDrvTermDatadriver_mk_port(ErlDrvPort port) + Make a erlang term port from a port + + +

This function converts a port handle to the erlang term + format, usable in the erl_drv_output_term(), and erl_drv_send_term() functions.

+

Note that this function is not thread-safe, not + even when the emulator with SMP support is used.

 + intdriver_monitor_process(ErlDrvPort port, ErlDrvTermData process, ErlDrvMonitor *monitor) Monitor a process from a driver @@ -1503,500 +1436,371 @@ typedef struct ErlIOVec { provided and > 0 if the process is no longer alive.

 + - intdriver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor) - Stop monitoring a process from a driver + intdriver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len) + Send data from driver to port owner - -

This function cancels a monitor created earlier.

-

The function returns 0 if a monitor was removed and > 0 - if the monitor did no longer exist.

+ +

The driver_output function is used to send data from + the driver up to the emulator. The data will be received as + terms or binary data, depending on how the driver port was + opened.

+

The data is queued in the port owner process' message + queue. Note that this does not yield to the emulator. (Since + the driver and the emulator run in the same thread.)

+

The parameter buf points to the data to send, and + len is the number of bytes.

+

The return value for all output functions is 0. (Unless the + driver is used for distribution, in which case it can fail + and return -1. For normal use, the output function always + returns 0.)

 + - ErlDrvTermDatadriver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor) - Retrieve the process id from a monitor + intdriver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len) + Send data from a driver binary to port owner - -

The function returns the process id associated with a living - monitor. It can be used in the process_exit call-back to - get the process identification for the exiting process.

-

The function returns driver_term_nil if the monitor - no longer exists.

+ +

This function sends data to port owner process from a + driver binary, it has a header buffer (hbuf + and hlen) just like driver_output2. The + hbuf parameter can be NULL.

+

The parameter offset is an offset into the binary and + len is the number of bytes to send.

+

Driver binaries are created with driver_alloc_binary.

+

The data in the header is sent as a list and the binary as + an Erlang binary in the tail of the list.

+

E.g. if hlen is 2, then the port owner process will + receive >]]]>.

+

The return value is 0 for normal use.

+

Note that, using the binary syntax in Erlang, the driver + application can match the header directly from the binary, + so the header can be put in the binary, and hlen can be set + to 0.

 + - intdriver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2) - Compare two monitors + intdriver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n) + Send term data from driver to port owner - -

This function is used to compare two ErlDrvMonitors. It - can also be used to imply some artificial order on monitors, - for whatever reason.

-

The function returns 0 if monitor1 and - monitor2 are equal, < 0 if monitor1 is less - than monitor2 and > 0 if monitor1 is greater - than monitor2.

+ +

driver_output_term() is deprecated and will + be removed in the OTP-R17 release. Use + erl_drv_output_term() + instead.

+ +

The parameters term and n do the same thing + as in erl_drv_output_term().

+

Note that this function is not thread-safe, not + even when the emulator with SMP support is used.

 + - voidadd_driver_entry(ErlDrvEntry *de) - Add a driver entry + intdriver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len) + Send data and binary data to port owner - -

This function adds a driver entry to the list of drivers - known by Erlang. The init function of the de - parameter is called.

- -

To use this function for adding drivers residing in - dynamically loaded code is dangerous. If the driver code - for the added driver resides in the same dynamically - loaded module (i.e. .so file) as a normal - dynamically loaded driver (loaded with the erl_ddll - interface), the caller should call driver_lock_driver before - adding driver entries.

-

Use of this function is generally deprecated.

- + +

The driver_output2 function first sends hbuf + (length in hlen) data as a list, regardless of port + settings. Then buf is sent as a binary or list. + E.g. if hlen is 3 then the port owner process will + receive [H1, H2, H3 | T].

+

The point of sending data as a list header, is to facilitate + matching on the data received.

+

The return value is 0 for normal use.

 + - intremove_driver_entry(ErlDrvEntry *de) - Remove a driver entry + intdriver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip) + Send vectorized data to port owner - -

This function removes a driver entry de previously - added with add_driver_entry.

-

Driver entries added by the erl_ddll erlang interface can - not be removed by using this interface.

+ +

This function sends data from an IO vector, ev, to + the port owner process. It has a header buffer (hbuf + and hlen), just like driver_output2.

+

The skip parameter is a number of bytes to skip of + the ev vector from the head.

+

You get vectors of ErlIOVec type from the driver + queue (see below), and the outputv driver entry + function. You can also make them yourself, if you want to + send several ErlDrvBinary buffers at once. Often + it is faster to use driver_output or + driver_output_binary.

+

E.g. if hlen is 2 and ev points to an array of + three binaries, the port owner process will receive >, <> | <>]]]>.

+

The return value is 0 for normal use.

+

The comment for driver_output_binary applies for + driver_outputv too.

 + - char *erl_errno_id(int error) - Get erlang error atom name from error number + ErlDrvPDLdriver_pdl_create(ErlDrvPort port) + Create a port data lock - -

This function returns the atom name of the erlang error, - given the error number in error. Error atoms are: - einval, enoent, etc. It can be used to make - error terms from the driver.

+ +

This function creates a port data lock associated with + the port. NOTE: Once a port data lock has + been created, it has to be locked during all operations + on the driver queue of the port.

+

On success a newly created port data lock is returned. On + failure NULL is returned. driver_pdl_create() will + fail if port is invalid or if a port data lock already has + been associated with the port.

 + - voiderl_drv_busy_msgq_limits(ErlDrvPort port, ErlDrvSizeT *low, ErlDrvSizeT *high) - Set and get limits for busy port message queue + longdriver_pdl_dec_refc(ErlDrvPDL pdl) + - -

Sets and gets limits that will be used for controling the - busy state of the port message queue.

-

The port message queue will be set into a busy - state when the amount of command data queued on the - message queue reaches the high limit. The port - message queue will be set into a not busy state when the - amount of command data queued on the message queue falls - below the low limit. Command data is in this - context data passed to the port using either - Port ! {Owner, {command, Data}}, or - port_command/[2,3]. Note that these limits - only concerns command data that have not yet reached the - port. The busy port - feature can be used for data that has reached the port.

+ +

This function decrements the reference count of + the port data lock passed as argument (pdl).

+

The current reference count after the decrement has + been performed is returned.

+

This function is thread-safe.

+ + -

Valid limits are values in the range - [ERL_DRV_BUSY_MSGQ_LIM_MIN, ERL_DRV_BUSY_MSGQ_LIM_MAX]. - Limits will be automatically adjusted to be sane. That is, - the system will adjust values so that the low limit used is - lower than or equal to the high limit used. By default the high - limit will be 8 kB and the low limit will be 4 kB.

+ + longdriver_pdl_get_refc(ErlDrvPDL pdl) + + + +

This function returns the current reference count of + the port data lock passed as argument (pdl).

+

This function is thread-safe.

+ + -

By passing a pointer to an integer variable containing - the value ERL_DRV_BUSY_MSGQ_READ_ONLY, currently used - limit will be read and written back to the integer variable. - A new limit can be set by passing a pointer to an integer - variable containing a valid limit. The passed value will be - written to the internal limit. The internal limit will then - be adjusted. After this the adjusted limit will be written - back to the integer variable from which the new value was - read. Values are in bytes.

- -

The busy message queue feature can be disabled either - by setting the ERL_DRV_FLAG_NO_BUSY_MSGQ - driver flag - in the driver_entry - used by the driver, or by calling this function with - ERL_DRV_BUSY_MSGQ_DISABLED as a limit (either low or - high). When this feature has been disabled it cannot be - enabled again. When reading the limits both of them - will be ERL_DRV_BUSY_MSGQ_DISABLED, if this - feature has been disabled.

- -

Processes sending command data to the port will be suspended - if either the port is busy or if the port message queue is - busy. Suspended processes will be resumed when neither the - port is busy, nor the port message queue is busy.

- -

For information about busy port functionality - see the documentation of the - set_busy_port() - function.

- - - voidset_busy_port(ErlDrvPort port, int on) - Signal or unsignal port as busy - - -

This function set and unset the busy state of the port. If - on is non-zero, the port is set to busy, if it's zero the port - is set to not busy. You typically want to combine - this feature with the busy - port message queue functionality.

-

Processes sending command data to the port will be suspended - if either the port is busy or if the port message queue - is busy. Suspended processes will be resumed when neither the - port is busy, nor the port message queue is busy. Command data - is in this context data passed to the port using either - Port ! {Owner, {command, Data}}, or - port_command/[2,3].

-

If the - - has been set in the - driver_entry, - data can be forced into the driver via - port_command(Port, Data, [force]) - even though the driver has signaled that it is busy. -

-

For information about busy port message queue functionality - see the documentation of the - erl_drv_busy_msgq_limits() - function.

- - - - voidset_port_control_flags(ErlDrvPort port, int flags) - Set flags on how to handle control entry function + longdriver_pdl_inc_refc(ErlDrvPDL pdl) + - -

This function sets flags for how the control driver entry - function will return data to the port owner process. (The - control function is called from port_control/3 - in erlang.)

-

Currently there are only two meaningful values for - flags: 0 means that data is returned in a list, and - PORT_CONTROL_FLAG_BINARY means data is returned as - a binary from control.

+ +

This function increments the reference count of + the port data lock passed as argument (pdl).

+

The current reference count after the increment has + been performed is returned.

+

This function is thread-safe.

 + - intdriver_failure_eof(ErlDrvPort port) - Fail with EOF + voiddriver_pdl_lock(ErlDrvPDL pdl) + Lock port data lock - -

This function signals to erlang that the driver has - encountered an EOF and should be closed, unless the port was - opened with the eof option, in that case eof is sent - to the port. Otherwise, the port is closed and an - 'EXIT' message is sent to the port owner process.

-

The return value is 0.

+ +

This function locks the port data lock passed as argument + (pdl).

+

This function is thread-safe.

 + - intdriver_failure_atom(ErlDrvPort port, char *string) - intdriver_failure_posix(ErlDrvPort port, int error) - intdriver_failure(ErlDrvPort port, int error) - Fail with error + voiddriver_pdl_unlock(ErlDrvPDL pdl) + Unlock port data lock - - - -

These functions signal to Erlang that the driver has - encountered an error and should be closed. The port is - closed and the tuple {'EXIT', error, Err}, is sent to - the port owner process, where error is an error atom - (driver_failure_atom and - driver_failure_posix), or an integer - (driver_failure).

-

The driver should fail only when in severe error situations, - when the driver cannot possibly keep open, for instance - buffer allocation gets out of memory. For normal errors - it is more appropriate to send error codes with - driver_output.

-

The return value is 0.

+ +

This function unlocks the port data lock passed as argument + (pdl).

+

This function is thread-safe.

 + - ErlDrvTermDatadriver_connected(ErlDrvPort port) - Return the port owner process + SysIOVec *driver_peekq(ErlDrvPort port, int *vlen) + Get the driver queue as a vector - -

This function returns the port owner process.

-

Note that this function is not thread-safe, not - even when the emulator with SMP support is used.

+ +

This function retrieves the driver queue as a pointer to an + array of SysIOVecs. It also returns the number of + elements in vlen. This is one of two ways to get data + out of the queue.

+

Nothing is removed from the queue by this function, that must be done + with driver_deq.

+

The returned array is suitable to use with the Unix system + call writev.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

 + - ErlDrvTermDatadriver_caller(ErlDrvPort port) - Return the process making the driver call + ErlDrvSizeTdriver_peekqv(ErlDrvPort port, ErlIOVec *ev) + Get the driver queue as an IO vector - -

This function returns the process id of the process that - made the current call to the driver. The process id can be - used with driver_send_term to send back data to the - caller. driver_caller() only returns valid data - when currently executing in one of the following driver - callbacks:

- - start - Called from open_port/2. - output - Called from erlang:send/2, and - erlang:port_command/2 - outputv - Called from erlang:send/2, and - erlang:port_command/2 - control - Called from erlang:port_control/3 - call - Called from erlang:port_call/3 - -

Note that this function is not thread-safe, not - even when the emulator with SMP support is used.

+ +

+ This function retrieves the driver queue into a supplied + ErlIOVec ev. It also returns the queue size. + This is one of two ways to get data out of the queue. +

+

+ If ev is NULL all ones i.e. -1 type cast to + ErlDrvSizeT is returned. +

+

Nothing is removed from the queue by this function, that must be done + with driver_deq.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

 + - interl_drv_output_term(ErlDrvTermData port, ErlDrvTermData* term, int n) - Send term data from driver to port owner + intdriver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len) + Push data at the head of the driver queue - -

This functions sends data in the special driver term - format to the port owner process. This is a fast way to - deliver term data from a driver. It also needs no binary - conversion, so the port owner process receives data as - normal Erlang terms. The - erl_drv_send_term() - functions can be used for sending to any arbitrary process - on the local node.

-

Note that the port parameter is not - an ordinary port handle, but a port handle converted using - driver_mk_port().

 -

The term parameter points to an array of - ErlDrvTermData, with n elements. This array - contains terms described in the driver term format. Every - term consists of one to four elements in the array. The - term first has a term type, and then arguments. The - port parameter specifies the sending port.

-

Tuples, maps and lists (with the exception of strings, see below), - are built in reverse polish notation, so that to build a - tuple, the elements are given first, and then the tuple - term, with a count. Likewise for lists and maps.

-

A tuple must be specified with the number of elements. (The - elements precede the ERL_DRV_TUPLE term.)

-

A list must be specified with the number of elements, - including the tail, which is the last term preceding - ERL_DRV_LIST.

-

A map must be specified with the number of key-value pairs N. - The key-value pairs must precede the ERL_DRV_MAP in this order: - key1,value1,key2,value2,...,keyN,valueN. - Duplicate keys are not allowed.

-

The special term ERL_DRV_STRING_CONS is used to - "splice" in a string in a list, a string given this way is - not a list per se, but the elements are elements of the - surrounding list.

- 
-Term type            Argument(s)
-===========================================
-ERL_DRV_NIL
-ERL_DRV_ATOM         ErlDrvTermData atom (from driver_mk_atom(char *string))
-ERL_DRV_INT          ErlDrvSInt integer
-ERL_DRV_UINT         ErlDrvUInt integer
-ERL_DRV_INT64        ErlDrvSInt64 *integer_ptr
-ERL_DRV_UINT64       ErlDrvUInt64 *integer_ptr
-ERL_DRV_PORT         ErlDrvTermData port (from driver_mk_port(ErlDrvPort port))
-ERL_DRV_BINARY       ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset
-ERL_DRV_BUF2BINARY   char *buf, ErlDrvUInt len
-ERL_DRV_STRING       char *str, int len
-ERL_DRV_TUPLE        int sz
-ERL_DRV_LIST         int sz
-ERL_DRV_PID          ErlDrvTermData pid (from driver_connected(ErlDrvPort port) or driver_caller(ErlDrvPort port))
-ERL_DRV_STRING_CONS  char *str, int len
-ERL_DRV_FLOAT        double *dbl
-ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
-ERL_DRV_MAP          int sz
-
-

The unsigned integer data type ErlDrvUInt and the - signed integer data type ErlDrvSInt are 64 bits wide - on a 64 bit runtime system and 32 bits wide on a 32 bit - runtime system. They were introduced in erts version 5.6, - and replaced some of the int arguments in the list above. -

-

The unsigned integer data type ErlDrvUInt64 and the - signed integer data type ErlDrvSInt64 are always 64 bits - wide. They were introduced in erts version 5.7.4. -

- -

To build the tuple {tcp, Port, [100 | Binary]}, the - following call could be made.

- - -

Where bin is a driver binary of length at least 50 - and drvport is a port handle. Note that the ERL_DRV_LIST - comes after the elements of the list, likewise the - ERL_DRV_TUPLE.

-

The term ERL_DRV_STRING_CONS is a way to construct - strings. It works differently from how ERL_DRV_STRING - works. ERL_DRV_STRING_CONS builds a string list in - reverse order, (as opposed to how ERL_DRV_LIST - works), concatenating the strings added to a list. The tail - must be given before ERL_DRV_STRING_CONS.

-

The ERL_DRV_STRING constructs a string, and ends - it. (So it's the same as ERL_DRV_NIL followed by - ERL_DRV_STRING_CONS.)

- -

- -

The ERL_DRV_EXT2TERM term type is used for passing a - term encoded with the - external format, - i.e., a term that has been encoded by - erlang:term_to_binary, - erl_interface, etc. - For example, if binp is a pointer to an ErlDrvBinary - that contains the term {17, 4711} encoded with the - external format - and you want to wrap it in a two tuple with the tag my_tag, - i.e., {my_tag, {17, 4711}}, you can do as follows: -

- orig_bytes, binp->orig_size - ERL_DRV_TUPLE, 2, - }; - erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); - ]]> - -

To build the map #{key1 => 100, key2 => {200, 300}}, the - following call could be made.

- - + +

This function puts data at the head of the driver queue. The + data in buf is copied (len bytes) and placed + at the beginning of the queue.

+

The return value is 0.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+ + -

If you want to pass a binary and don't already have the content - of the binary in an ErlDrvBinary, you can benefit from using - ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary - via driver_alloc_binary() and then pass the binary via - ERL_DRV_BINARY. The runtime system will often allocate - binaries smarter if ERL_DRV_BUF2BINARY is used. - However, if the content of the binary to pass already resides in - an ErlDrvBinary, it is normally better to pass the binary - using ERL_DRV_BINARY and the ErlDrvBinary in question. -

-

The ERL_DRV_UINT, ERL_DRV_BUF2BINARY, and - ERL_DRV_EXT2TERM term types were introduced in the 5.6 - version of erts. -

-

This function is only thread-safe when the emulator with SMP - support is used.

+ + intdriver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) + Push binary at the head of the driver queue + + +

This function puts data in the binary bin, at + offset with length len at the head of the + driver queue. It is most often faster than + driver_pushq, because the data doesn't have to be + copied.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

+

The return value is 0.

 + - intdriver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n) - Send term data from driver to port owner + intdriver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip) + Push vector at the head of the driver queue - -

driver_output_term() is deprecated and will - be removed in the OTP-R17 release. Use - erl_drv_output_term() - instead.

- -

The parameters term and n do the same thing - as in erl_drv_output_term().

-

Note that this function is not thread-safe, not - even when the emulator with SMP support is used.

+ +

This function puts the data in ev, skipping the first + skip bytes of it, at the head of the driver queue. + It is faster than driver_pushq, because the data + doesn't have to be copied.

+

The return value is 0.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

 + - ErlDrvTermDatadriver_mk_atom(char* string) - Make an atom from a name + intdriver_read_timer(ErlDrvPort port, unsigned long *time_left) + Read the time left before timeout - -

This function returns an atom given a name - string. The atom is created and won't change, so the - return value may be saved and reused, which is faster than - looking up the atom several times.

-

Note that this function is not thread-safe, not - even when the emulator with SMP support is used.

+ +

This function reads the current time of a timer, and places + the result in time_left. This is the time in + milliseconds, before the timeout will occur.

+

The return value is 0.

 + - ErlDrvTermDatadriver_mk_port(ErlDrvPort port) - Make a erlang term port from a port + void *driver_realloc(void *ptr, ErlDrvSizeT size) + Resize an allocated memory block - -

This function converts a port handle to the erlang term - format, usable in the erl_drv_output_term(), and erl_drv_send_term() functions.

-

Note that this function is not thread-safe, not - even when the emulator with SMP support is used.

+ +

This function resizes a memory block, either in place, or by + allocating a new block, copying the data and freeing the old + block. A pointer is returned to the reallocated memory. On + failure (out of memory), NULL is returned. (This is + most often a wrapper for realloc.)

+

This function is thread-safe.

 + - interl_drv_send_term(ErlDrvTermData port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) - Send term data to other process than port owner process + ErlDrvBinary *driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size) + Resize a driver binary - -

This function is the only way for a driver to send data to - other processes than the port owner process. The - receiver parameter specifies the process to receive - the data.

-

Note that the port parameter is not - an ordinary port handle, but a port handle converted using - driver_mk_port().

 -

The parameters port, term and n do the same thing - as in erl_drv_output_term().

+ +

This function resizes a driver binary, while keeping the + data. The resized driver binary is returned. On failure (out + of memory), NULL is returned.

This function is only thread-safe when the emulator with SMP support is used.

 + + + intdriver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on) + Provide an event for having the emulator call the driver + + +

This function is used by drivers to provide the emulator with + events to check for. This enables the emulator to call the driver + when something has happened asynchronously.

+

The event argument identifies an OS-specific event object. + On Unix systems, the functions select/poll are used. The + event object must be a socket or pipe (or other object that + select/poll can use). + On windows, the Win32 API function WaitForMultipleObjects + is used. This places other restrictions on the event object. + Refer to the Win32 SDK documentation.

+

The on parameter should be 1 for setting events + and 0 for clearing them.

+

The mode argument is a bitwise-or combination of + ERL_DRV_READ, ERL_DRV_WRITE and ERL_DRV_USE. + The first two specify whether to wait for read events and/or write + events. A fired read event will call + ready_input + while a fired write event will call + ready_output. +

+ +

Some OS (Windows) do not differentiate between read and write events. + The call-back for a fired event then only depends on the value of mode.

+ +

ERL_DRV_USE specifies if we are using the event object or if we want to close it. + On an emulator with SMP support, it is not safe to clear all events + and then close the event object after driver_select has + returned. Another thread may still be using the event object + internally. To safely close an event object call + driver_select with ERL_DRV_USE and on==0. That + will clear all events and then call + stop_select + when it is safe to close the event object. + ERL_DRV_USE should be set together with the first event + for an event object. It is harmless to set ERL_DRV_USE + even though it already has been done. Clearing all events but keeping + ERL_DRV_USE set will indicate that we are using the event + object and probably will set events for it again.

+ +

ERL_DRV_USE was added in OTP release R13. Old drivers will still work + as before. But it is recommended to update them to use ERL_DRV_USE and + stop_select to make sure that event objects are closed in a safe way.

+ +

The return value is 0 (failure, -1, only if the + ready_input/ready_output is + NULL).

+ + + intdriver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) Send term data to other process than port owner process @@ -2018,368 +1822,338 @@ ERL_DRV_MAP int sz support is used.

 - - longdriver_async (ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*)) - Perform an asynchronous call within a driver - - -

This function performs an asynchronous call. The function - async_invoke is invoked in a thread separate from the - emulator thread. This enables the driver to perform - time-consuming, blocking operations without blocking the - emulator.

-

The async thread pool size can be set with the - +A - command line argument of erl(1). - If no async thread pool is available, the call is made - synchronously in the thread calling driver_async(). The - current number of async threads in the async thread pool can be - retrieved via - driver_system_info().

-

If there is a thread pool available, a thread will be - used. If the key argument is null, the threads from the - pool are used in a round-robin way, each call to - driver_async uses the next thread in the pool. With the - key argument set, this behaviour is changed. The two - same values of *key always get the same thread.

-

To make sure that a driver instance always uses the same - thread, the following call can be used:

-

- -

It is enough to initialize myKey once for each - driver instance.

-

If a thread is already working, the calls will be - queued up and executed in order. Using the same thread for - each driver instance ensures that the calls will be made in - sequence.

-

The async_data is the argument to the functions - async_invoke and async_free. It's typically a - pointer to a structure that contains a pipe or event that - can be used to signal that the async operation completed. - The data should be freed in async_free.

-

When the async operation is done, ready_async driver - entry function is called. If ready_async is null in - the driver entry, the async_free function is called - instead.

-

The return value is -1 if the driver_async call - fails.

- -

As of erts version 5.5.4.3 the default stack size for - threads in the async-thread pool is 16 kilowords, - i.e., 64 kilobyte on 32-bit architectures. - This small default size has been chosen since the - amount of async-threads might be quite large. The - default stack size is enough for drivers delivered - with Erlang/OTP, but might not be sufficiently large - for other dynamically linked in drivers that use the - driver_async() functionality. A suggested stack size - for threads in the async-thread pool can be configured - via the - +a - command line argument of - erl(1).

- - - - unsigned intdriver_async_port_key (ErlDrvPort port) - Calculate an async key from an ErlDrvPort + intdriver_set_timer(ErlDrvPort port, unsigned long time) + Set a timer to call the driver - -

This function calculates a key for later use in driver_async(). The keys are - evenly distributed so that a fair mapping between port id's - and async thread id's is achieved.

- -

Before OTP-R16, the actual port id could be used as a key - with proper casting, but after the rewrite of the port - subsystem, this is no longer the case. With this function, you - can achieve the same distribution based on port id's as before - OTP-R16.

- + +

This function sets a timer on the driver, which will count + down and call the driver when it is timed out. The + time parameter is the time in milliseconds before the + timer expires.

+

When the timer reaches 0 and expires, the driver entry + function timeout is called.

+

Note that there is only one timer on each driver instance; + setting a new timer will replace an older one.

+

Return value is 0 (-1 only when the timeout driver + function is NULL).

 + - intdriver_lock_driver(ErlDrvPort port) - Make sure the driver is never unloaded + ErlDrvSizeTdriver_sizeq(ErlDrvPort port) + Return the size of the driver queue - -

This function locks the driver used by the port port - in memory for the rest of the emulator process' - lifetime. After this call, the driver behaves as one of Erlang's - statically linked in drivers.

+ +

This function returns the number of bytes currently in the + driver queue.

+

This function can be called from an arbitrary thread if a + port data lock + associated with the port is locked by the calling + thread during the call.

 + - ErlDrvPortdriver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data) - Create a new port (driver instance) + voiddriver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size) + Get information about the Erlang runtime system -

This function creates a new port executing the same driver - code as the port creating the new port. - A short description of the arguments:

- - port - The port handle of the port (driver instance) creating - the new port. - owner_pid - The process id of the Erlang process which will be - owner of the new port. This process will be linked - to the new port. You usually want to use - driver_caller(port) as owner_pid. - name - The port name of the new port. You usually want to - use the same port name as the driver name - (driver_name - field of the - driver_entry). - drv_data - The driver defined handle that will be passed in subsequent - calls to driver call-backs. Note, that the - driver start call-back - will not be called for this new driver instance. - The driver defined handle is normally created in the - driver start call-back - when a port is created via - erlang:open_port/2. - -

The caller of driver_create_port() is allowed to - manipulate the newly created port when driver_create_port() - has returned. When - port level locking - is used, the creating port is, however, only allowed to - manipulate the newly created port until the current driver - call-back that was called by the emulator returns.

- -

When - port level locking - is used, the creating port is only allowed to manipulate - the newly created port until the current driver call-back - returns.

- + +

This function will write information about the Erlang runtime + system into the + ErlDrvSysInfo + structure referred to by the first argument. The second + argument should be the size of the + ErlDrvSysInfo + structure, i.e., sizeof(ErlDrvSysInfo).

+

See the documentation of the + ErlDrvSysInfo + structure for information about specific fields.

 - - - voiderl_drv_init_ack(ErlDrvPort port, ErlDrvData res) - Acknowledge the start of the port + + ErlDrvSizeTdriver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len) + Collect data segments into a buffer - -

Arguments:

- - port - The port handle of the port (driver instance) creating - doing the acknowledgment. - - res - The result of the port initialization. This can be the same values - as the return value of start, - i.e any of the error codes or the ErlDrvData that is to be used for this - port. - - -

- When this function is called the initiating erlang:open_port call is - returned as if the start - function had just been called. It can only be used when the - ERL_DRV_FLAG_USE_INIT_ACK - flag has been set on the linked-in driver. -

+ +

This function collects several segments of data, referenced + by ev, by copying them in order to the buffer + buf, of the size len.

+

If the data is to be sent from the driver to the port owner + process, it is faster to use driver_outputv.

+

The return value is the space left in the buffer, i.e. if + the ev contains less than len bytes it's the + difference, and if ev contains len bytes or + more, it's 0. This is faster if there is more than one header byte, + since the binary syntax can construct integers directly from + the binary.

 - voiderl_drv_set_os_pid(ErlDrvPort port, ErlDrvSInt pid) - Set the os_pid for the port + voiderl_drv_busy_msgq_limits(ErlDrvPort port, ErlDrvSizeT *low, ErlDrvSizeT *high) + Set and get limits for busy port message queue - -

Arguments:

- - port - The port handle of the port (driver instance) to set the pid on. - - pid - The pid to set. - -

- Set the os_pid seen when doing erlang:port_info/2 on this port. -

+ +

Sets and gets limits that will be used for controling the + busy state of the port message queue.

+

The port message queue will be set into a busy + state when the amount of command data queued on the + message queue reaches the high limit. The port + message queue will be set into a not busy state when the + amount of command data queued on the message queue falls + below the low limit. Command data is in this + context data passed to the port using either + Port ! {Owner, {command, Data}}, or + port_command/[2,3]. Note that these limits + only concerns command data that have not yet reached the + port. The busy port + feature can be used for data that has reached the port.

+ +

Valid limits are values in the range + [ERL_DRV_BUSY_MSGQ_LIM_MIN, ERL_DRV_BUSY_MSGQ_LIM_MAX]. + Limits will be automatically adjusted to be sane. That is, + the system will adjust values so that the low limit used is + lower than or equal to the high limit used. By default the high + limit will be 8 kB and the low limit will be 4 kB.

+ +

By passing a pointer to an integer variable containing + the value ERL_DRV_BUSY_MSGQ_READ_ONLY, currently used + limit will be read and written back to the integer variable. + A new limit can be set by passing a pointer to an integer + variable containing a valid limit. The passed value will be + written to the internal limit. The internal limit will then + be adjusted. After this the adjusted limit will be written + back to the integer variable from which the new value was + read. Values are in bytes.

+ +

The busy message queue feature can be disabled either + by setting the ERL_DRV_FLAG_NO_BUSY_MSGQ + driver flag + in the driver_entry + used by the driver, or by calling this function with + ERL_DRV_BUSY_MSGQ_DISABLED as a limit (either low or + high). When this feature has been disabled it cannot be + enabled again. When reading the limits both of them + will be ERL_DRV_BUSY_MSGQ_DISABLED, if this + feature has been disabled.

+ +

Processes sending command data to the port will be suspended + if either the port is busy or if the port message queue is + busy. Suspended processes will be resumed when neither the + port is busy, nor the port message queue is busy.

+ +

For information about busy port functionality + see the documentation of the + set_busy_port() + function.

 - interl_drv_thread_create(char *name, - ErlDrvTid *tid, - void * (*func)(void *), - void *arg, - ErlDrvThreadOpts *opts) - Create a thread + voiderl_drv_cond_broadcast(ErlDrvCond *cnd) + Broadcast on a condition variable - +

Arguments:

- name - A string identifying the created thread. It will be used - to identify the thread in planned future debug - functionality. - - tid - A pointer to a thread identifier variable. - func - A pointer to a function to execute in the created thread. - arg - A pointer to argument to the func function. - opts - A pointer to thread options to use or NULL. + cnd + A pointer to a condition variable to broadcast on. -

This function creates a new thread. On success 0 is returned; - otherwise, an errno value is returned to indicate the error. - The newly created thread will begin executing in the function pointed - to by func, and func will be passed arg as - argument. When erl_drv_thread_create() returns the thread - identifier of the newly created thread will be available in - *tid. opts can be either a NULL pointer, or a - pointer to an - ErlDrvThreadOpts - structure. If opts is a NULL pointer, default options - will be used; otherwise, the passed options will be used. -

-

You are not allowed to allocate the - ErlDrvThreadOpts - structure by yourself. It has to be allocated and - initialized by - erl_drv_thread_opts_create(). -

-

The created thread will terminate either when func returns - or if - erl_drv_thread_exit() - is called by the thread. The exit value of the thread is either - returned from func or passed as argument to - erl_drv_thread_exit(). - The driver creating the thread has the responsibility of joining the - thread, via - erl_drv_thread_join(), - before the driver is unloaded. It is not possible to create - "detached" threads, i.e., threads that don't need to be joined. +

This function broadcasts on a condition variable. That is, if + other threads are waiting on the condition variable being + broadcast on, all of them will be woken.

-

All created threads need to be joined by the driver before - it is unloaded. If the driver fails to join all threads - created before it is unloaded, the runtime system will - most likely crash when the code of the driver is unloaded. -

This function is thread-safe.

 - ErlDrvThreadOpts *erl_drv_thread_opts_create(char *name) - Create thread options + ErlDrvCond *erl_drv_cond_create(char *name) + Create a condition variable - +

Arguments:

name - A string identifying the created thread options. It will be used - to identify the thread options in planned future debug - functionality. + A string identifying the created condition variable. It + will be used to identify the condition variable in planned + future debug functionality. -

This function allocates and initialize a thread option - structure. On failure NULL is returned. A thread option - structure is used for passing options to - erl_drv_thread_create(). - If the structure isn't modified before it is passed to - erl_drv_thread_create(), - the default values will be used. -

-

You are not allowed to allocate the - ErlDrvThreadOpts - structure by yourself. It has to be allocated and - initialized by erl_drv_thread_opts_create(). -

+

This function creates a condition variable and returns a + pointer to it. On failure NULL is returned. The driver + creating the condition variable has the responsibility of + destroying it before the driver is unloaded.

This function is thread-safe.

 - voiderl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts) - Destroy thread options + voiderl_drv_cond_destroy(ErlDrvCond *cnd) + Destroy a condition variable - +

Arguments:

- opts - A pointer to thread options to destroy. + cnd + A pointer to a condition variable to destroy. -

This function destroys thread options previously created by - erl_drv_thread_opts_create(). +

This function destroys a condition variable previously + created by + erl_drv_cond_create().

-

This function is thread-safe.

+

This function is thread-safe.

 + + char *erl_drv_cond_name(ErlDrvCond *cnd) + Get name of driver mutex. + + +

Arguments:

+ + cnd + A pointer to an initialized condition. + +

+ Returns a pointer to the name of the condition. +

+ +

This function is intended for debugging purposes only.

+ + + - voiderl_drv_thread_exit(void *exit_value) - Terminate calling thread + voiderl_drv_cond_signal(ErlDrvCond *cnd) + Signal on a condition variable - +

Arguments:

- exit_value - A pointer to an exit value or NULL. + cnd + A pointer to a condition variable to signal on. -

This function terminates the calling thread with the exit - value passed as argument. You are only allowed to terminate - threads created with - erl_drv_thread_create(). - The exit value can later be retrieved by another thread via - erl_drv_thread_join(). +

This function signals on a condition variable. That is, if + other threads are waiting on the condition variable being + signaled, one of them will be woken.

This function is thread-safe.

 - interl_drv_thread_join(ErlDrvTid tid, void **exit_value) - Join with another thread + voiderl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx) + Wait on a condition variable - +

Arguments:

- tid - The thread identifier of the thread to join. - exit_value - A pointer to a pointer to an exit value, or NULL. + cnd + A pointer to a condition variable to wait on. + mtx + A pointer to a mutex to unlock while waiting. + + -

This function joins the calling thread with another thread, i.e., - the calling thread is blocked until the thread identified by - tid has terminated. On success 0 is returned; - otherwise, an errno value is returned to indicate the error. - A thread can only be joined once. The behavior of joining - more than once is undefined, an emulator crash is likely. If - exit_value == NULL, the exit value of the terminated thread - will be ignored; otherwise, the exit value of the terminated thread - will be stored at *exit_value. +

This function waits on a condition variable. The calling + thread is blocked until another thread wakes it by signaling + or broadcasting on the condition variable. Before the calling + thread is blocked it unlocks the mutex passed as argument, and + when the calling thread is woken it locks the same mutex before + returning. That is, the mutex currently has to be locked by + the calling thread when calling this function.

+

erl_drv_cond_wait() might return even though + no-one has signaled or broadcast on the condition + variable. Code calling erl_drv_cond_wait() should + always be prepared for erl_drv_cond_wait() + returning even though the condition that the thread was + waiting for hasn't occurred. That is, when returning from + erl_drv_cond_wait() always check if the condition + has occurred, and if not call erl_drv_cond_wait() + again. +

This function is thread-safe.

 - ErlDrvTiderl_drv_thread_self(void) - Get the thread identifier of the current thread + interl_drv_consume_timeslice(ErlDrvPort port, int percent) + Give the runtime system a hint about how much CPU time the + current driver callback call has consumed - -

This function returns the thread identifier of the - calling thread. -

-

This function is thread-safe.

+ +

Arguments:

+ + port + Port handle of the executing port. + percent + Approximate consumed fraction of a full + time-slice in percent. + +

Give the runtime system a hint about how much CPU time the + current driver callback call has consumed since last hint, or + since the start of the callback if no previous hint has been given. + The time is given as a fraction, in percent, of a full time-slice + that a port is allowed to execute before it should surrender the + CPU to other runnable ports or processes. Valid range is + [1, 100]. The scheduling time-slice is not an exact entity, + but can usually be approximated to about 1 millisecond.

+ +

Note that it is up to the runtime system to determine if and + how to use this information. Implementations on some platforms + may use other means in order to determine the consumed fraction + of the time-slice. Lengthy driver callbacks should regardless of + this frequently call the erl_drv_consume_timeslice() + function in order to determine if it is allowed to continue + execution or not.

+ +

erl_drv_consume_timeslice() returns a non-zero value + if the time-slice has been exhausted, and zero if the callback is + allowed to continue execution. If a non-zero value is + returned the driver callback should return as soon as possible in + order for the port to be able to yield.

+ +

This function is provided to better support co-operative scheduling, + improve system responsiveness, and to make it easier to prevent + misbehaviors of the VM due to a port monopolizing a scheduler thread. + It can be used when dividing length work into a number of repeated + driver callback calls without the need to use threads. Also see the + important warning text at the + beginning of this document.

 + + ErlDrvTimeerl_drv_convert_time_unit(ErlDrvTime val, ErlDrvTimeUnit from, ErlDrvTimeUnit to) + Convert time unit of a time value + + +

Arguments:

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

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

+

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

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + + interl_drv_equal_tids(ErlDrvTid tid1, ErlDrvTid tid2) Compare thread identifiers for equality @@ -2406,6 +2180,97 @@ ERL_DRV_MAP int sz + + interl_drv_getenv(const char *key, char *value, size_t *value_size) + Get the value of an environment variable + + +

Arguments:

+ + key + A null terminated string containing the + name of the environment variable. + value + A pointer to an output buffer. + value_size + A pointer to an integer. The integer is both used for + passing input and output sizes (see below). + + +

This function retrieves the value of an environment variable. + When called, *value_size should contain the size of + the value buffer. On success 0 is returned, + the value of the environment variable has been written to + the value buffer, and *value_size contains the + string length (excluding the terminating null character) of + the value written to the value buffer. On failure, + i.e., no such environment variable was found, a value less than + 0 is returned. When the size of the value + buffer is too small, a value greater than 0 is returned + and *value_size has been set to the buffer size needed. +

+

Do not use libc's getenv or similar + C library interfaces from a driver. +

+

This function is thread-safe.

+ + + + + voiderl_drv_init_ack(ErlDrvPort port, ErlDrvData res) + Acknowledge the start of the port + + +

Arguments:

+ + port + The port handle of the port (driver instance) creating + doing the acknowledgment. + + res + The result of the port initialization. This can be the same values + as the return value of start, + i.e any of the error codes or the ErlDrvData that is to be used for this + port. + + +

+ When this function is called the initiating erlang:open_port call is + returned as if the start + function had just been called. It can only be used when the + ERL_DRV_FLAG_USE_INIT_ACK + flag has been set on the linked-in driver. +

+ + + + + ErlDrvTimeerl_drv_monotonic_time(ErlDrvTimeUnit time_unit) + Get Erlang Monotonic Time + + +

Arguments:

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

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

+

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

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + + ErlDrvMutex *erl_drv_mutex_create(char *name) Create a mutex @@ -2469,6 +2334,25 @@ ERL_DRV_MAP int sz + + char *erl_drv_mutex_name(ErlDrvMutex *mtx) + Get name of driver mutex. + + +

Arguments:

+ + mtx + A pointer to an initialized mutex. + +

+ Returns a pointer to the name of the mutex. +

+ +

This function is intended for debugging purposes only.

+ + + + interl_drv_mutex_trylock(ErlDrvMutex *mtx) Try lock a mutex @@ -2510,112 +2394,209 @@ ERL_DRV_MAP int sz - ErlDrvCond *erl_drv_cond_create(char *name) - Create a condition variable + interl_drv_output_term(ErlDrvTermData port, ErlDrvTermData* term, int n) + Send term data from driver to port owner - -

Arguments:

- - name - A string identifying the created condition variable. It - will be used to identify the condition variable in planned - future debug functionality. - - -

This function creates a condition variable and returns a - pointer to it. On failure NULL is returned. The driver - creating the condition variable has the responsibility of - destroying it before the driver is unloaded.

-

This function is thread-safe.

- - + +

This functions sends data in the special driver term + format to the port owner process. This is a fast way to + deliver term data from a driver. It also needs no binary + conversion, so the port owner process receives data as + normal Erlang terms. The + erl_drv_send_term() + functions can be used for sending to any arbitrary process + on the local node.

+

Note that the port parameter is not + an ordinary port handle, but a port handle converted using + driver_mk_port().

 +

The term parameter points to an array of + ErlDrvTermData, with n elements. This array + contains terms described in the driver term format. Every + term consists of one to four elements in the array. The + term first has a term type, and then arguments. The + port parameter specifies the sending port.

+

Tuples, maps and lists (with the exception of strings, see below), + are built in reverse polish notation, so that to build a + tuple, the elements are given first, and then the tuple + term, with a count. Likewise for lists and maps.

+

A tuple must be specified with the number of elements. (The + elements precede the ERL_DRV_TUPLE term.)

+

A list must be specified with the number of elements, + including the tail, which is the last term preceding + ERL_DRV_LIST.

+

A map must be specified with the number of key-value pairs N. + The key-value pairs must precede the ERL_DRV_MAP in this order: + key1,value1,key2,value2,...,keyN,valueN. + Duplicate keys are not allowed.

+

The special term ERL_DRV_STRING_CONS is used to + "splice" in a string in a list, a string given this way is + not a list per se, but the elements are elements of the + surrounding list.

+ 
+Term type            Argument(s)
+===========================================
+ERL_DRV_NIL
+ERL_DRV_ATOM         ErlDrvTermData atom (from driver_mk_atom(char *string))
+ERL_DRV_INT          ErlDrvSInt integer
+ERL_DRV_UINT         ErlDrvUInt integer
+ERL_DRV_INT64        ErlDrvSInt64 *integer_ptr
+ERL_DRV_UINT64       ErlDrvUInt64 *integer_ptr
+ERL_DRV_PORT         ErlDrvTermData port (from driver_mk_port(ErlDrvPort port))
+ERL_DRV_BINARY       ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset
+ERL_DRV_BUF2BINARY   char *buf, ErlDrvUInt len
+ERL_DRV_STRING       char *str, int len
+ERL_DRV_TUPLE        int sz
+ERL_DRV_LIST         int sz
+ERL_DRV_PID          ErlDrvTermData pid (from driver_connected(ErlDrvPort port) or driver_caller(ErlDrvPort port))
+ERL_DRV_STRING_CONS  char *str, int len
+ERL_DRV_FLOAT        double *dbl
+ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
+ERL_DRV_MAP          int sz
+
+

The unsigned integer data type ErlDrvUInt and the + signed integer data type ErlDrvSInt are 64 bits wide + on a 64 bit runtime system and 32 bits wide on a 32 bit + runtime system. They were introduced in erts version 5.6, + and replaced some of the int arguments in the list above. +

+

The unsigned integer data type ErlDrvUInt64 and the + signed integer data type ErlDrvSInt64 are always 64 bits + wide. They were introduced in erts version 5.7.4. +

- - voiderl_drv_cond_destroy(ErlDrvCond *cnd) - Destroy a condition variable - - -

Arguments:

- - cnd - A pointer to a condition variable to destroy. - -

This function destroys a condition variable previously - created by - erl_drv_cond_create(). +

To build the tuple {tcp, Port, [100 | Binary]}, the + following call could be made.

+ + +

Where bin is a driver binary of length at least 50 + and drvport is a port handle. Note that the ERL_DRV_LIST + comes after the elements of the list, likewise the + ERL_DRV_TUPLE.

+

The term ERL_DRV_STRING_CONS is a way to construct + strings. It works differently from how ERL_DRV_STRING + works. ERL_DRV_STRING_CONS builds a string list in + reverse order, (as opposed to how ERL_DRV_LIST + works), concatenating the strings added to a list. The tail + must be given before ERL_DRV_STRING_CONS.

+

The ERL_DRV_STRING constructs a string, and ends + it. (So it's the same as ERL_DRV_NIL followed by + ERL_DRV_STRING_CONS.)

+ +

+ +

The ERL_DRV_EXT2TERM term type is used for passing a + term encoded with the + external format, + i.e., a term that has been encoded by + erlang:term_to_binary, + erl_interface, etc. + For example, if binp is a pointer to an ErlDrvBinary + that contains the term {17, 4711} encoded with the + external format + and you want to wrap it in a two tuple with the tag my_tag, + i.e., {my_tag, {17, 4711}}, you can do as follows:

-

This function is thread-safe.

- - + orig_bytes, binp->orig_size + ERL_DRV_TUPLE, 2, + }; + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); + ]]> - - voiderl_drv_cond_signal(ErlDrvCond *cnd) - Signal on a condition variable - - -

Arguments:

- - cnd - A pointer to a condition variable to signal on. - -

This function signals on a condition variable. That is, if - other threads are waiting on the condition variable being - signaled, one of them will be woken. +

To build the map #{key1 => 100, key2 => {200, 300}}, the + following call could be made.

+ + + +

If you want to pass a binary and don't already have the content + of the binary in an ErlDrvBinary, you can benefit from using + ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary + via driver_alloc_binary() and then pass the binary via + ERL_DRV_BINARY. The runtime system will often allocate + binaries smarter if ERL_DRV_BUF2BINARY is used. + However, if the content of the binary to pass already resides in + an ErlDrvBinary, it is normally better to pass the binary + using ERL_DRV_BINARY and the ErlDrvBinary in question.

-

This function is thread-safe.

- - - - - voiderl_drv_cond_broadcast(ErlDrvCond *cnd) - Broadcast on a condition variable - - -

Arguments:

- - cnd - A pointer to a condition variable to broadcast on. - -

This function broadcasts on a condition variable. That is, if - other threads are waiting on the condition variable being - broadcast on, all of them will be woken. +

The ERL_DRV_UINT, ERL_DRV_BUF2BINARY, and + ERL_DRV_EXT2TERM term types were introduced in the 5.6 + version of erts.

-

This function is thread-safe.

+

This function is only thread-safe when the emulator with SMP + support is used.

 - voiderl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx) - Wait on a condition variable + interl_drv_putenv(const char *key, char *value) + Set the value of an environment variable - +

Arguments:

- cnd - A pointer to a condition variable to wait on. - mtx - A pointer to a mutex to unlock while waiting. - - + key + A null terminated string containing the + name of the environment variable. + value + A null terminated string containing the + new value of the environment variable. -

This function waits on a condition variable. The calling - thread is blocked until another thread wakes it by signaling - or broadcasting on the condition variable. Before the calling - thread is blocked it unlocks the mutex passed as argument, and - when the calling thread is woken it locks the same mutex before - returning. That is, the mutex currently has to be locked by - the calling thread when calling this function. +

This function sets the value of an environment variable. + It returns 0 on success, and a value != 0 on + failure.

-

erl_drv_cond_wait() might return even though - no-one has signaled or broadcast on the condition - variable. Code calling erl_drv_cond_wait() should - always be prepared for erl_drv_cond_wait() - returning even though the condition that the thread was - waiting for hasn't occurred. That is, when returning from - erl_drv_cond_wait() always check if the condition - has occurred, and if not call erl_drv_cond_wait() - again. -

+

The result of passing the empty string ("") as a value + is platform dependent. On some platforms the value of the + variable is set to the empty string, on others, the + environment variable is removed.

+ +

Do not use libc's putenv or similar + C library interfaces from a driver. +

This function is thread-safe.

 @@ -2659,6 +2640,25 @@ ERL_DRV_MAP int sz + + char *erl_drv_rwlock_name(ErlDrvRWLock *rwlck) + Get name of driver mutex. + + +

Arguments:

+ + rwlck + A pointer to an initialized r/w-lock. + +

+ Returns a pointer to the name of the r/w-lock. +

+ +

This function is intended for debugging purposes only.

+ + + + voiderl_drv_rwlock_rlock(ErlDrvRWLock *rwlck) Read lock an rwlock @@ -2682,29 +2682,6 @@ ERL_DRV_MAP int sz - - interl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck) - Try to read lock an rwlock - - -

Arguments:

- - rwlck - A pointer to an rwlock to try to read lock. - -

This function tries to read lock an rwlock. If successful - 0, is returned; otherwise, EBUSY is returned. - A thread which currently has read or read/write locked the - rwlock may not try to lock the same rwlock again. -

-

If you leave an rwlock locked in an emulator thread - when you let the thread out of your control, you will - very likely deadlock the whole emulator. -

-

This function is thread-safe.

- - - voiderl_drv_rwlock_runlock(ErlDrvRWLock *rwlck) Read unlock an rwlock @@ -2745,29 +2722,6 @@ ERL_DRV_MAP int sz - - interl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck) - Try to read/write lock an rwlock - - -

Arguments:

- - rwlck - A pointer to an rwlock to try to read/write lock. - -

This function tries to read/write lock an rwlock. If successful - 0, is returned; otherwise, EBUSY is returned. - A thread which currently has read or read/write locked the - rwlock may not try to lock the same rwlock again. -

-

If you leave an rwlock locked in an emulator thread - when you let the thread out of your control, you will - very likely deadlock the whole emulator. -

-

This function is thread-safe.

- - - voiderl_drv_rwlock_rwunlock(ErlDrvRWLock *rwlck) Read/Write unlock an rwlock @@ -2786,276 +2740,200 @@ ERL_DRV_MAP int sz - interl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key) - Create a thread specific data key + interl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck) + Try to read lock an rwlock - +

Arguments:

- name - A string identifying the created key. It will be used - to identify the key in planned future debug - functionality. - - key - A pointer to a thread specific data key variable. + rwlck + A pointer to an rwlock to try to read lock. -

This function creates a thread specific data key. On success - 0 is returned; otherwise, an errno value is returned - to indicate the error. The driver creating the key has the - responsibility of destroying it before the driver is unloaded. +

This function tries to read lock an rwlock. If successful + 0, is returned; otherwise, EBUSY is returned. + A thread which currently has read or read/write locked the + rwlock may not try to lock the same rwlock again.

+

If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator. +

This function is thread-safe.

 - voiderl_drv_tsd_key_destroy(ErlDrvTSDKey key) - Destroy a thread specific data key + interl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck) + Try to read/write lock an rwlock - +

Arguments:

- key - A thread specific data key to destroy. + rwlck + A pointer to an rwlock to try to read/write lock. -

This function destroys a thread specific data key - previously created by - erl_drv_tsd_key_create(). - All thread specific data using this key in all threads - have to be cleared (see - erl_drv_tsd_set()) - prior to the call to erl_drv_tsd_key_destroy(). +

This function tries to read/write lock an rwlock. If successful + 0, is returned; otherwise, EBUSY is returned. + A thread which currently has read or read/write locked the + rwlock may not try to lock the same rwlock again.

-

A destroyed key is very likely to be reused soon. - Therefore, if you fail to clear the thread specific - data using this key in a thread prior to destroying - the key, you will very likely get unexpected - errors in other parts of the system. +

If you leave an rwlock locked in an emulator thread + when you let the thread out of your control, you will + very likely deadlock the whole emulator.

This function is thread-safe.

 - voiderl_drv_tsd_set(ErlDrvTSDKey key, void *data) - Set thread specific data + interl_drv_send_term(ErlDrvTermData port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) + Send term data to other process than port owner process - -

Arguments:

- - key - A thread specific data key. - data - A pointer to data to associate with key - in calling thread. - - -

This function sets thread specific data associated with - key for the calling thread. You are only allowed to set - thread specific data for threads while they are fully under your - control. For example, if you set thread specific data in a thread - calling a driver call-back function, it has to be cleared, i.e. - set to NULL, before returning from the driver call-back - function. -

-

If you fail to clear thread specific data in an - emulator thread before letting it out of your control, - you might not ever be able to clear this data with - later unexpected errors in other parts of the system as - a result. -

-

This function is thread-safe.

+ +

This function is the only way for a driver to send data to + other processes than the port owner process. The + receiver parameter specifies the process to receive + the data.

+

Note that the port parameter is not + an ordinary port handle, but a port handle converted using + driver_mk_port().

 +

The parameters port, term and n do the same thing + as in erl_drv_output_term().

+

This function is only thread-safe when the emulator with SMP + support is used.

 - void *erl_drv_tsd_get(ErlDrvTSDKey key) - Get thread specific data + voiderl_drv_set_os_pid(ErlDrvPort port, ErlDrvSInt pid) + Set the os_pid for the port - +

Arguments:

- key - A thread specific data key. - -

This function returns the thread specific data - associated with key for the calling thread. - If no data has been associated with key for - the calling thread, NULL is returned. -

-

This function is thread-safe.

+ port + The port handle of the port (driver instance) to set the pid on. + + pid + The pid to set. + +

+ Set the os_pid seen when doing erlang:port_info/2 on this port. +

- interl_drv_putenv(const char *key, char *value) - Set the value of an environment variable + interl_drv_thread_create(char *name, + ErlDrvTid *tid, + void * (*func)(void *), + void *arg, + ErlDrvThreadOpts *opts) + Create a thread - +

Arguments:

- key - A null terminated string containing the - name of the environment variable. - value - A null terminated string containing the - new value of the environment variable. + name + A string identifying the created thread. It will be used + to identify the thread in planned future debug + functionality. + + tid + A pointer to a thread identifier variable. + func + A pointer to a function to execute in the created thread. + arg + A pointer to argument to the func function. + opts + A pointer to thread options to use or NULL. -

This function sets the value of an environment variable. - It returns 0 on success, and a value != 0 on - failure. +

This function creates a new thread. On success 0 is returned; + otherwise, an errno value is returned to indicate the error. + The newly created thread will begin executing in the function pointed + to by func, and func will be passed arg as + argument. When erl_drv_thread_create() returns the thread + identifier of the newly created thread will be available in + *tid. opts can be either a NULL pointer, or a + pointer to an + ErlDrvThreadOpts + structure. If opts is a NULL pointer, default options + will be used; otherwise, the passed options will be used.

-

The result of passing the empty string ("") as a value - is platform dependent. On some platforms the value of the - variable is set to the empty string, on others, the - environment variable is removed.

- -

Do not use libc's putenv or similar - C library interfaces from a driver. +

You are not allowed to allocate the + ErlDrvThreadOpts + structure by yourself. It has to be allocated and + initialized by + erl_drv_thread_opts_create(). +

+

The created thread will terminate either when func returns + or if + erl_drv_thread_exit() + is called by the thread. The exit value of the thread is either + returned from func or passed as argument to + erl_drv_thread_exit(). + The driver creating the thread has the responsibility of joining the + thread, via + erl_drv_thread_join(), + before the driver is unloaded. It is not possible to create + "detached" threads, i.e., threads that don't need to be joined. +

+

All created threads need to be joined by the driver before + it is unloaded. If the driver fails to join all threads + created before it is unloaded, the runtime system will + most likely crash when the code of the driver is unloaded.

This function is thread-safe.

 + - interl_drv_getenv(const char *key, char *value, size_t *value_size) - Get the value of an environment variable + voiderl_drv_thread_exit(void *exit_value) + Terminate calling thread - +

Arguments:

- key - A null terminated string containing the - name of the environment variable. - value - A pointer to an output buffer. - value_size - A pointer to an integer. The integer is both used for - passing input and output sizes (see below). - + exit_value + A pointer to an exit value or NULL. -

This function retrieves the value of an environment variable. - When called, *value_size should contain the size of - the value buffer. On success 0 is returned, - the value of the environment variable has been written to - the value buffer, and *value_size contains the - string length (excluding the terminating null character) of - the value written to the value buffer. On failure, - i.e., no such environment variable was found, a value less than - 0 is returned. When the size of the value - buffer is too small, a value greater than 0 is returned - and *value_size has been set to the buffer size needed. +

This function terminates the calling thread with the exit + value passed as argument. You are only allowed to terminate + threads created with + erl_drv_thread_create(). + The exit value can later be retrieved by another thread via + erl_drv_thread_join().

-

Do not use libc's getenv or similar - C library interfaces from a driver. -

This function is thread-safe.

 + - interl_drv_consume_timeslice(ErlDrvPort port, int percent) - Give the runtime system a hint about how much CPU time the - current driver callback call has consumed + interl_drv_thread_join(ErlDrvTid tid, void **exit_value) + Join with another thread - +

Arguments:

- port - Port handle of the executing port. - percent - Approximate consumed fraction of a full - time-slice in percent. + tid + The thread identifier of the thread to join. + exit_value + A pointer to a pointer to an exit value, or NULL. -

Give the runtime system a hint about how much CPU time the - current driver callback call has consumed since last hint, or - since the start of the callback if no previous hint has been given. - The time is given as a fraction, in percent, of a full time-slice - that a port is allowed to execute before it should surrender the - CPU to other runnable ports or processes. Valid range is - [1, 100]. The scheduling time-slice is not an exact entity, - but can usually be approximated to about 1 millisecond.

- -

Note that it is up to the runtime system to determine if and - how to use this information. Implementations on some platforms - may use other means in order to determine the consumed fraction - of the time-slice. Lengthy driver callbacks should regardless of - this frequently call the erl_drv_consume_timeslice() - function in order to determine if it is allowed to continue - execution or not.

- -

erl_drv_consume_timeslice() returns a non-zero value - if the time-slice has been exhausted, and zero if the callback is - allowed to continue execution. If a non-zero value is - returned the driver callback should return as soon as possible in - order for the port to be able to yield.

- -

This function is provided to better support co-operative scheduling, - improve system responsiveness, and to make it easier to prevent - misbehaviors of the VM due to a port monopolizing a scheduler thread. - It can be used when dividing length work into a number of repeated - driver callback calls without the need to use threads. Also see the - important warning text at the - beginning of this document.

+

This function joins the calling thread with another thread, i.e., + the calling thread is blocked until the thread identified by + tid has terminated. On success 0 is returned; + otherwise, an errno value is returned to indicate the error. + A thread can only be joined once. The behavior of joining + more than once is undefined, an emulator crash is likely. If + exit_value == NULL, the exit value of the terminated thread + will be ignored; otherwise, the exit value of the terminated thread + will be stored at *exit_value. +

+

This function is thread-safe.

 - - char *erl_drv_cond_name(ErlDrvCond *cnd) - Get name of driver mutex. - - -

Arguments:

- - cnd - A pointer to an initialized condition. - -

- Returns a pointer to the name of the condition. -

- -

This function is intended for debugging purposes only.

- - - - - - char *erl_drv_mutex_name(ErlDrvMutex *mtx) - Get name of driver mutex. - - -

Arguments:

- - mtx - A pointer to an initialized mutex. - -

- Returns a pointer to the name of the mutex. -

- -

This function is intended for debugging purposes only.

- - - - - - char *erl_drv_rwlock_name(ErlDrvRWLock *rwlck) - Get name of driver mutex. - - -

Arguments:

- - rwlck - A pointer to an initialized r/w-lock. - -

- Returns a pointer to the name of the r/w-lock. -

- -

This function is intended for debugging purposes only.

- - - - char *erl_drv_thread_name(ErlDrvTid tid) Get name of driver mutex. @@ -3075,32 +2953,64 @@ ERL_DRV_MAP int sz - - ErlDrvTimeerl_drv_monotonic_time(ErlDrvTimeUnit time_unit) - Get Erlang Monotonic Time - - -

Arguments:

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

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

-

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

-

See also:

- - ErlDrvTime - ErlDrvTimeUnit - - - + + ErlDrvThreadOpts *erl_drv_thread_opts_create(char *name) + Create thread options + + +

Arguments:

+ + name + A string identifying the created thread options. It will be used + to identify the thread options in planned future debug + functionality. + + +

This function allocates and initialize a thread option + structure. On failure NULL is returned. A thread option + structure is used for passing options to + erl_drv_thread_create(). + If the structure isn't modified before it is passed to + erl_drv_thread_create(), + the default values will be used. +

+

You are not allowed to allocate the + ErlDrvThreadOpts + structure by yourself. It has to be allocated and + initialized by erl_drv_thread_opts_create(). +

+

This function is thread-safe.

+ + + + + voiderl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts) + Destroy thread options + + +

Arguments:

+ + opts + A pointer to thread options to destroy. + +

This function destroys thread options previously created by + erl_drv_thread_opts_create(). +

+

This function is thread-safe.

+ + + + + ErlDrvTiderl_drv_thread_self(void) + Get the thread identifier of the current thread + + +

This function returns the thread identifier of the + calling thread. +

+

This function is thread-safe.

+ + ErlDrvTimeerl_drv_time_offset(ErlDrvTimeUnit time_unit) @@ -3128,33 +3038,180 @@ ERL_DRV_MAP int sz - - ErlDrvTimeerl_drv_convert_time_unit(ErlDrvTime val, ErlDrvTimeUnit from, ErlDrvTimeUnit to) - Convert time unit of a time value - - -

Arguments:

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

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

-

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

-

See also:

- - ErlDrvTime - ErlDrvTimeUnit - - - + + void *erl_drv_tsd_get(ErlDrvTSDKey key) + Get thread specific data + + +

Arguments:

+ + key + A thread specific data key. + +

This function returns the thread specific data + associated with key for the calling thread. + If no data has been associated with key for + the calling thread, NULL is returned. +

+

This function is thread-safe.

+ + + + + interl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key) + Create a thread specific data key + + +

Arguments:

+ + name + A string identifying the created key. It will be used + to identify the key in planned future debug + functionality. + + key + A pointer to a thread specific data key variable. + +

This function creates a thread specific data key. On success + 0 is returned; otherwise, an errno value is returned + to indicate the error. The driver creating the key has the + responsibility of destroying it before the driver is unloaded. +

+

This function is thread-safe.

+ + + + + voiderl_drv_tsd_key_destroy(ErlDrvTSDKey key) + Destroy a thread specific data key + + +

Arguments:

+ + key + A thread specific data key to destroy. + +

This function destroys a thread specific data key + previously created by + erl_drv_tsd_key_create(). + All thread specific data using this key in all threads + have to be cleared (see + erl_drv_tsd_set()) + prior to the call to erl_drv_tsd_key_destroy(). +

+

A destroyed key is very likely to be reused soon. + Therefore, if you fail to clear the thread specific + data using this key in a thread prior to destroying + the key, you will very likely get unexpected + errors in other parts of the system. +

+

This function is thread-safe.

+ + + + + voiderl_drv_tsd_set(ErlDrvTSDKey key, void *data) + Set thread specific data + + +

Arguments:

+ + key + A thread specific data key. + data + A pointer to data to associate with key + in calling thread. + + +

This function sets thread specific data associated with + key for the calling thread. You are only allowed to set + thread specific data for threads while they are fully under your + control. For example, if you set thread specific data in a thread + calling a driver call-back function, it has to be cleared, i.e. + set to NULL, before returning from the driver call-back + function. +

+

If you fail to clear thread specific data in an + emulator thread before letting it out of your control, + you might not ever be able to clear this data with + later unexpected errors in other parts of the system as + a result. +

+

This function is thread-safe.

+ + + + + char *erl_errno_id(int error) + Get erlang error atom name from error number + + +

This function returns the atom name of the erlang error, + given the error number in error. Error atoms are: + einval, enoent, etc. It can be used to make + error terms from the driver.

+ + + + + intremove_driver_entry(ErlDrvEntry *de) + Remove a driver entry + + +

This function removes a driver entry de previously + added with add_driver_entry.

+

Driver entries added by the erl_ddll erlang interface can + not be removed by using this interface.

+ + + + + voidset_busy_port(ErlDrvPort port, int on) + Signal or unsignal port as busy + + +

This function set and unset the busy state of the port. If + on is non-zero, the port is set to busy, if it's zero the port + is set to not busy. You typically want to combine + this feature with the busy + port message queue functionality.

+

Processes sending command data to the port will be suspended + if either the port is busy or if the port message queue + is busy. Suspended processes will be resumed when neither the + port is busy, nor the port message queue is busy. Command data + is in this context data passed to the port using either + Port ! {Owner, {command, Data}}, or + port_command/[2,3].

+

If the + + has been set in the + driver_entry, + data can be forced into the driver via + port_command(Port, Data, [force]) + even though the driver has signaled that it is busy. +

+

For information about busy port message queue functionality + see the documentation of the + erl_drv_busy_msgq_limits() + function.

+ + + + voidset_port_control_flags(ErlDrvPort port, int flags) + Set flags on how to handle control entry function + + +

This function sets flags for how the control driver entry + function will return data to the port owner process. (The + control function is called from port_control/3 + in erlang.)

+

Currently there are only two meaningful values for + flags: 0 means that data is returned in a list, and + PORT_CONTROL_FLAG_BINARY means data is returned as + a binary from control.

+ +
SEE ALSO diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index f3921f1922..8ed042f6f9 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -124,6 +124,7 @@ ok Note however that unused local stub functions will be optimized away by the compiler causing loading of the NIF library to fail.

+

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 new Erlang code will have to load its own NIF library (or maybe choose not @@ -401,7 +402,7 @@ ok as I/O bound jobs, dirty I/O schedulers might starve ordinary schedulers. I/O bound jobs are expected to either block waiting for I/O, and/or spend a limited amount of time moving data. -

+

To schedule a dirty NIF for execution, the appropriate @@ -434,7 +435,6 @@ ok dirty schedulers need to complete before the block operation can complete.

-

A lot of operations communicating with a process executing a dirty NIF can, however, complete while it is executing the @@ -442,7 +442,6 @@ ok process_info(), setting its group leader, register/unregister its name, etc.

-

Termination of a process executing a dirty NIF can only be completed up to a certain point while it is executing the @@ -462,7 +461,6 @@ ok heap, and process control block will be delayed until the dirty NIF has completed.

-

Currently known issues that are planned to be fixed:

@@ -756,11 +754,14 @@ typedef enum {
- void *enif_alloc(size_t size) + + void *enif_alloc(size_t size) Allocate dynamic memory

Allocate memory of size bytes. Return NULL if allocation failed.

 - intenif_alloc_binary(size_t size, ErlNifBinary* bin) + + + intenif_alloc_binary(size_t size, ErlNifBinary* bin) Create a new binary

Allocate a new binary of size size bytes. Initialize the structure pointed to by bin to @@ -773,7 +774,9 @@ typedef enum {

Return true on success or false if allocation failed.

 - ErlNifEnv *enif_alloc_env() + + + ErlNifEnv *enif_alloc_env() Create a new environment

Allocate a new process independent environment. The environment can be used to hold terms that is not bound to any process. Such terms can @@ -783,17 +786,15 @@ typedef enum {

Return pointer to the new environment.

 - void *enif_alloc_resource(ErlNifResourceType* type, unsigned size) + + + void *enif_alloc_resource(ErlNifResourceType* type, unsigned size) Allocate a memory managed resource object

Allocate a memory managed resource object of type type and size size bytes.

 - voidenif_clear_env(ErlNifEnv* env) - Clear an environment for reuse -

Free all terms in an environment and clear it for reuse. The environment must - have been allocated with enif_alloc_env. -

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

Create a term that is the result of decoding the binary data @@ -812,7 +813,19 @@ typedef enum {

- intenif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs) + + + + voidenif_clear_env(ErlNifEnv* env) + Clear an environment for reuse +

Free all terms in an environment and clear it for reuse. The environment must + have been allocated with enif_alloc_env. +

+ + + + + intenif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs) Compare two terms

Return an integer less than, equal to, or greater than zero if lhs is found, respectively, to be less than, @@ -820,32 +833,44 @@ typedef enum { operators ==, /=, =<, <, >= and > (but not =:= or =/=).

 - voidenif_cond_broadcast(ErlNifCond *cnd) + + + voidenif_cond_broadcast(ErlNifCond *cnd)

Same as erl_drv_cond_broadcast.

- ErlNifCond *enif_cond_create(char *name) + + + ErlNifCond *enif_cond_create(char *name)

Same as erl_drv_cond_create.

- voidenif_cond_destroy(ErlNifCond *cnd) + + + voidenif_cond_destroy(ErlNifCond *cnd)

Same as erl_drv_cond_destroy.

- voidenif_cond_signal(ErlNifCond *cnd) + + + voidenif_cond_signal(ErlNifCond *cnd)

Same as erl_drv_cond_signal.

- voidenif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx) + + + voidenif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)

Same as erl_drv_cond_wait.

- intenif_consume_timeslice(ErlNifEnv *env, int percent) + + + intenif_consume_timeslice(ErlNifEnv *env, int percent)

Give the runtime system a hint about how much CPU time the current NIF call has consumed since last hint, or since the start of the NIF if no previous hint has been given. @@ -869,9 +894,9 @@ typedef enum { a number of repeated NIF-calls without the need to create threads. See also the warning text at the beginning of this document.

 - + ErlNifTimeenif_convert_time_unit(ErlNifTime val, ErlNifTimeUnit from, ErlNifTimeUnit to) Convert time unit of a time value @@ -911,21 +936,28 @@ typedef enum { - intenif_equal_tids(ErlNifTid tid1, ErlNifTid tid2) + + intenif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)

Same as erl_drv_equal_tids.

- voidenif_free(void* ptr) + + + voidenif_free(void* ptr) Free dynamic memory

Free memory allocated by enif_alloc.

 - voidenif_free_env(ErlNifEnv* env) + + + voidenif_free_env(ErlNifEnv* env) Free an environment allocated with enif_alloc_env

Free an environment allocated with enif_alloc_env. All terms created in the environment will be freed as well.

 - intenif_get_atom(ErlNifEnv* env, ERL_NIF_TERM term, char* buf, unsigned size, ErlNifCharEncoding encode) + + + intenif_get_atom(ErlNifEnv* env, ERL_NIF_TERM term, char* buf, unsigned size, ErlNifCharEncoding encode) Get the text representation of an atom term

Write a null-terminated string, in the buffer pointed to by buf of size size, consisting of the string @@ -935,77 +967,102 @@ typedef enum { term is not an atom with maximum length of size-1.

 - intenif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode) + + + intenif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode) Get the length of atom term

Set *len to the length (number of bytes excluding terminating null character) of the atom term with encoding encode. Return true on success or false if term is not an atom.

 - intenif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp) + + + intenif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp) Read a floating-point number term

Set *dp to the floating point value of term. Return true on success or false if term is not a float.

 - intenif_get_int(ErlNifEnv* env, ERL_NIF_TERM term, int* ip) + + + intenif_get_int(ErlNifEnv* env, ERL_NIF_TERM term, int* ip) Read an integer term

Set *ip to the integer value of term. Return true on success or false if term is not an integer or is outside the bounds of type int.

 - intenif_get_int64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifSInt64* ip) + + + intenif_get_int64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifSInt64* ip) Read a 64-bit integer term

Set *ip to the integer value of term. Return true on success or false if term is not an integer or is outside the bounds of a signed 64-bit integer.

 - intenif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid) + + + intenif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid) Read an local pid term

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

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

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

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

Set *head and *tail from list and return true, or return false if list is not a non-empty list.

 - intenif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len) + + + intenif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len) Get the length of list term

Set *len to the length of list term and return true, or return false if term is not a proper list.

 - intenif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip) + + + intenif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip) Read an long integer term

Set *ip to the long integer value of term and return true, or return false if term is not an integer or is outside the bounds of type long int.

 - intenif_get_map_size(ErlNifEnv* env, ERL_NIF_TERM term, size_t *size) + + + intenif_get_map_size(ErlNifEnv* env, ERL_NIF_TERM term, size_t *size) Read the size of a map term

Set *size to the number of key-value pairs in the map term and return true, or return false if term is not a map.

 - intenif_get_map_value(ErlNifEnv* env, ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value) + + + intenif_get_map_value(ErlNifEnv* env, ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value) Get the value of a key in a map

Set *value to the value associated with key in the map map and return true. Return false if map is not a map or if map does not contain key.

 - intenif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp) + + intenif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp) Get the pointer to a resource object

Set *objp to point to the resource object referred to by term.

Return true on success or false if term is not a handle to a resource object of type type.

 - intenif_get_string(ErlNifEnv* env, + + + intenif_get_string(ErlNifEnv* env, ERL_NIF_TERM list, char* buf, unsigned size, ErlNifCharEncoding encode) Get a C-string from a list @@ -1020,7 +1077,9 @@ typedef enum { The written string is always null-terminated unless buffer size is less than 1.

 - intenif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array) + + + intenif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array) Inspect the elements of a tuple

If term is a tuple, set *array to point to an array containing the elements of the tuple and set @@ -1030,29 +1089,39 @@ typedef enum { is zero.

Return true on success or false if term is not a tuple.

 - intenif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip) + + + intenif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip) Read an unsigned integer term

Set *ip to the unsigned integer value of term and return true, or return false if term is not an unsigned integer or is outside the bounds of type unsigned int.

 - intenif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip) + + + intenif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip) Read an unsigned 64-bit integer term

Set *ip to the unsigned integer value of term and return true, or return false if term is not an unsigned integer or is outside the bounds of an unsigned 64-bit integer.

 - intenif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip) + + + intenif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip) Read an unsigned integer term

Set *ip to the unsigned long integer value of term and return true, or return false if term is not an unsigned integer or is outside the bounds of type unsigned long.

 - intenif_getenv(const char* key, char* value, size_t *value_size) + + + intenif_getenv(const char* key, char* value, size_t *value_size) Get the value of an environment variable

Same as erl_drv_getenv.

 - intenif_has_pending_exception(ErlNifEnv* env, ERL_NIF_TERM* reason) + + + intenif_has_pending_exception(ErlNifEnv* env, ERL_NIF_TERM* reason) Check if an exception has been raised

Return true if a pending exception is associated with the environment env. If reason is a null pointer, ignore it. @@ -1065,13 +1134,17 @@ typedef enum { and enif_raise_exception.

 - intenif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin) + + + intenif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin) Inspect the content of a binary

Initialize the structure pointed to by bin with information about the binary term bin_term. Return true on success or false if bin_term is not a binary.

 - intenif_inspect_iolist_as_binary(ErlNifEnv* + + + intenif_inspect_iolist_as_binary(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifBinary* bin) Inspect the content of an iolist @@ -1082,81 +1155,115 @@ typedef enum { iolist.

 - intenif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is an atom

Return true if term is an atom.

 - intenif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a binary

Return true if term is a binary

 - intenif_is_current_process_alive(ErlNifEnv* env) + + + intenif_is_current_process_alive(ErlNifEnv* env) Determine if currently executing process is alive or not.

Return true if currently executing process is currently alive; otherwise false.

This function can only be used from a NIF-calling thread, and with an environment corresponding to currently executing processes.

 - intenif_is_empty_list(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_empty_list(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is an empty list

Return true if term is an empty list.

 - intenif_is_exception(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_exception(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is an exception

Return true if term is an exception.

 - intenif_is_map(ErlNifEnv* env, ERL_NIF_TERM term) - Determine if a term is a map -

Return true if term is a map, false otherwise.

 - - intenif_is_number(ErlNifEnv* env, ERL_NIF_TERM term) - Determine if a term is a number (integer or float) -

Return true if term is a number.

 - - intenif_is_fun(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_fun(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a fun

Return true if term is a fun.

 - intenif_is_identical(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs) + + + intenif_is_identical(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs) Erlang operator =:=

Return true if the two terms are identical. Corresponds to the Erlang operators =:= and =/=.

 - intenif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_list(ErlNifEnv* env, ERL_NIF_TERM term) + Determine if a term is a list +

Return true if term is a list.

 + + + + intenif_is_map(ErlNifEnv* env, ERL_NIF_TERM term) + Determine if a term is a map +

Return true if term is a map, false otherwise.

 + + + + intenif_is_number(ErlNifEnv* env, ERL_NIF_TERM term) + Determine if a term is a number (integer or float) +

Return true if term is a number.

 + + + + intenif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a pid

Return true if term is a pid.

 - intenif_is_port(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_port(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a port

Return true if term is a port.

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

Return true if port_id is currently alive.

This function is only thread-safe when the emulator with SMP support is used. It can only be used in a non-SMP emulator from a NIF-calling thread.

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

Return true if pid is currently alive.

This function is only thread-safe when the emulator with SMP support is used. It can only be used in a non-SMP emulator from a NIF-calling thread.

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

Return true if term is a reference.

 - intenif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term) + + + intenif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a tuple

Return true if term is a tuple.

 - intenif_is_list(ErlNifEnv* env, ERL_NIF_TERM term) - Determine if a term is a list -

Return true if term is a list.

 - - intenif_keep_resource(void* obj) + + + intenif_keep_resource(void* obj) Add a reference to a resource object

Add a reference to resource object obj obtained from enif_alloc_resource. @@ -1164,7 +1271,9 @@ typedef enum { a call to enif_release_resource before the object will be destructed.

 - ERL_NIF_TERMenif_make_atom(ErlNifEnv* env, const char* name) + + + ERL_NIF_TERMenif_make_atom(ErlNifEnv* env, const char* name) Create an atom term

Create an atom term from the null-terminated C-string name with iso-latin-1 encoding. If the length of name exceeds the maximum length @@ -1172,7 +1281,9 @@ typedef enum { enif_make_badarg.

- ERL_NIF_TERMenif_make_atom_len(ErlNifEnv* env, const char* name, size_t len) + + + ERL_NIF_TERMenif_make_atom_len(ErlNifEnv* env, const char* name, size_t len) Create an atom term

Create an atom term from the string name with length len. Null-characters are treated as any other characters. If len is greater than the maximum length @@ -1180,7 +1291,9 @@ typedef enum { enif_make_badarg.

- ERL_NIF_TERMenif_make_badarg(ErlNifEnv* env) + + + ERL_NIF_TERMenif_make_badarg(ErlNifEnv* env) Make a badarg exception

Make a badarg exception to be returned from a NIF, and associate it with the environment env. Once a NIF or any function @@ -1200,27 +1313,35 @@ typedef enum { requirement is now lifted as the return value from the NIF is ignored if enif_make_badarg has been invoked.

 - ERL_NIF_TERMenif_make_binary(ErlNifEnv* env, ErlNifBinary* bin) + + + ERL_NIF_TERMenif_make_binary(ErlNifEnv* env, ErlNifBinary* bin) Make a binary term

Make a binary term from bin. Any ownership of the binary data will be transferred to the created term and bin should be considered read-only for the rest of the NIF call and then as released.

 - ERL_NIF_TERMenif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term) + + + ERL_NIF_TERMenif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term) Make a copy of a term

Make a copy of term src_term. The copy will be created in environment dst_env. The source term may be located in any environment.

 - ERL_NIF_TERMenif_make_double(ErlNifEnv* env, double d) + + + ERL_NIF_TERMenif_make_double(ErlNifEnv* env, double d) Create a floating-point term

Create a floating-point term from a double. If the double argument is not finite or is NaN, enif_make_double invokes enif_make_badarg.

- intenif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode) + + + intenif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode) Create an existing atom term

Try to create the term of an already existing atom from the null-terminated C-string name with encoding @@ -1230,7 +1351,9 @@ typedef enum { allowed for an atom (255 characters), enif_make_existing_atom returns false.

 - intenif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding) + + + intenif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding) Create an existing atom term

Try to create the term of an already existing atom from the string name with length len and encoding @@ -1240,21 +1363,29 @@ typedef enum { than the maximum length allowed for an atom (255 characters), enif_make_existing_atom_len returns false.

 - ERL_NIF_TERMenif_make_int(ErlNifEnv* env, int i) + + + ERL_NIF_TERMenif_make_int(ErlNifEnv* env, int i) Create an integer term

Create an integer term.

 - ERL_NIF_TERMenif_make_int64(ErlNifEnv* env, ErlNifSInt64 i) + + + ERL_NIF_TERMenif_make_int64(ErlNifEnv* env, ErlNifSInt64 i) Create an integer term

Create an integer term from a signed 64-bit integer.

 - ERL_NIF_TERMenif_make_list(ErlNifEnv* env, unsigned cnt, ...) + + + ERL_NIF_TERMenif_make_list(ErlNifEnv* env, unsigned cnt, ...) Create a list term

Create an ordinary list term of length cnt. Expects cnt number of arguments (after cnt) of type ERL_NIF_TERM as the elements of the list. An empty list is returned if cnt is 0.

 - ERL_NIF_TERMenif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1) + + + ERL_NIF_TERMenif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1) ERL_NIF_TERMenif_make_list2(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2) ERL_NIF_TERMenif_make_list3(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3) ERL_NIF_TERMenif_make_list4(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4) @@ -1269,34 +1400,28 @@ typedef enum { enif_make_list to get a compile time error if the number of arguments does not match.

 - ERL_NIF_TERMenif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail) + + + ERL_NIF_TERMenif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail) Create a list cell

Create a list cell [head | tail].

 - ERL_NIF_TERMenif_make_list_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt) + + + ERL_NIF_TERMenif_make_list_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt) Create a list term from an array

Create an ordinary list containing the elements of array arr of length cnt. An empty list is returned if cnt is 0.

 - ERL_NIF_TERMenif_make_long(ErlNifEnv* env, long int i) + + + ERL_NIF_TERMenif_make_long(ErlNifEnv* env, long int i) Create an integer term from a long int

Create an integer term from a long int.

 - unsigned char *enif_make_new_binary(ErlNifEnv* env, size_t size, ERL_NIF_TERM* termp) - Allocate and create a new binary term -

Allocate a binary of size size 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 - ErlNifBinary. The drawbacks are - that the binary can not be kept between NIF calls and it can not be - reallocated.

Return a pointer to the raw binary data and set - *termp to the binary term.

 - - ERL_NIF_TERMenif_make_new_map(ErlNifEnv* env) - Make an empty map term -

Make an empty map term.

 - - intenif_make_map_put(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value, ERL_NIF_TERM* map_out) + + + intenif_make_map_put(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value, ERL_NIF_TERM* map_out) Insert key-value pair in map

Make a copy of map map_in and insert key with value. If key already exists in map_in, the old @@ -1305,15 +1430,9 @@ typedef enum { map_in is not a map.

The map_in term must belong to the environment env.

 - intenif_make_map_update(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value, ERL_NIF_TERM* map_out) - Replace value for key in map -

Make a copy of map map_in and replace the old associated - value for key with new_value. If successful set - *map_out to the new map and return true. Return false if - map_in is not a map or if it does no contain key.

-

The map_in term must belong to the environment env.

 - - intenif_make_map_remove(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out) + + + intenif_make_map_remove(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out) Remove key from map

If map map_in contains key, make a copy of map_in in *map_out and remove key and associated @@ -1322,15 +1441,49 @@ typedef enum { map_in is not a map.

The map_in term must belong to the environment env.

 - ERL_NIF_TERMenif_make_pid(ErlNifEnv* env, const ErlNifPid* pid) + + + intenif_make_map_update(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value, ERL_NIF_TERM* map_out) + Replace value for key in map +

Make a copy of map map_in and replace the old associated + value for key with new_value. If successful set + *map_out to the new map and return true. Return false if + map_in is not a map or if it does no contain key.

+

The map_in term must belong to the environment env.

 + + + + unsigned char *enif_make_new_binary(ErlNifEnv* env, size_t size, ERL_NIF_TERM* termp) + Allocate and create a new binary term +

Allocate a binary of size size 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 + ErlNifBinary. The drawbacks are + that the binary can not be kept between NIF calls and it can not be + reallocated.

Return a pointer to the raw binary data and set + *termp to the binary term.

 + + + + ERL_NIF_TERMenif_make_new_map(ErlNifEnv* env) + Make an empty map term +

Make an empty map term.

 + + + + ERL_NIF_TERMenif_make_pid(ErlNifEnv* env, const ErlNifPid* pid) Make a pid term

Make a pid term from *pid.

 - ERL_NIF_TERMenif_make_ref(ErlNifEnv* env) + + + ERL_NIF_TERMenif_make_ref(ErlNifEnv* env) Create a reference

Create a reference like erlang:make_ref/0.

 - ERL_NIF_TERMenif_make_resource(ErlNifEnv* env, void* obj) + + + ERL_NIF_TERMenif_make_resource(ErlNifEnv* env, void* obj) Create an opaque handle to a resource object

Create an opaque handle to a memory managed resource object obtained by enif_alloc_resource. @@ -1347,7 +1500,9 @@ typedef enum { same node. Other operations such as matching or term_to_binary will have unpredictable (but harmless) results.

 - ERL_NIF_TERMenif_make_resource_binary(ErlNifEnv* env, void* obj, const void* data, size_t size) + + + ERL_NIF_TERMenif_make_resource_binary(ErlNifEnv* env, void* obj, const void* data, size_t size) Create a custom binary term

Create a binary term that is memory managed by a resource object obj obtained by enif_alloc_resource. @@ -1365,7 +1520,9 @@ typedef enum { enif_release_resource.

 - intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out) + + + intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out) Create the reverse of a list

Set *list_out to the reverse list of the list list_in and return true, or return false if list_in is not a list. This function should only be used on @@ -1373,18 +1530,24 @@ typedef enum { nif returns.

The list_in term must belong to the environment env.

 - ERL_NIF_TERMenif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding) + + + ERL_NIF_TERMenif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding) Create a string

Create a list containing the characters of the null-terminated string string with encoding encoding.

 - ERL_NIF_TERMenif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding) + + + ERL_NIF_TERMenif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding) Create a string

Create a list containing the characters of the string string with length len and encoding encoding. Null-characters are treated as any other characters.

 - ERL_NIF_TERMenif_make_sub_binary(ErlNifEnv* + + + ERL_NIF_TERMenif_make_sub_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, size_t pos, size_t size) Make a subbinary term

Make a subbinary of binary bin_term, starting at @@ -1393,13 +1556,17 @@ typedef enum { pos+size must be less or equal to the number of whole bytes in bin_term.

 - ERL_NIF_TERMenif_make_tuple(ErlNifEnv* env, unsigned cnt, ...) + + + ERL_NIF_TERMenif_make_tuple(ErlNifEnv* env, unsigned cnt, ...) Create a tuple term

Create a tuple term of arity cnt. Expects cnt number of arguments (after cnt) of type ERL_NIF_TERM as the elements of the tuple.

 - ERL_NIF_TERMenif_make_tuple1(ErlNifEnv* env, ERL_NIF_TERM e1) + + + ERL_NIF_TERMenif_make_tuple1(ErlNifEnv* env, ERL_NIF_TERM e1) ERL_NIF_TERMenif_make_tuple2(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2) ERL_NIF_TERMenif_make_tuple3(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3) ERL_NIF_TERMenif_make_tuple4(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4) @@ -1414,19 +1581,32 @@ typedef enum { enif_make_tuple to get a compile time error if the number of arguments does not match.

 - ERL_NIF_TERMenif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt) + + + ERL_NIF_TERMenif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt) Create a tuple term from an array

Create a tuple containing the elements of array arr of length cnt.

 - ERL_NIF_TERMenif_make_uint(ErlNifEnv* env, unsigned int i) + + + ERL_NIF_TERMenif_make_uint(ErlNifEnv* env, unsigned int i) Create an unsigned integer term

Create an integer term from an unsigned int.

 - ERL_NIF_TERMenif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i) + + + ERL_NIF_TERMenif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i) Create an unsigned integer term

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

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

Create an integer term from an unsigned long int.

 + + ERL_NIF_TERMenif_make_unique_integer(ErlNifEnv *env, ErlNifUniqueInteger properties) @@ -1444,11 +1624,9 @@ typedef enum {

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

Create an integer term from an unsigned long int.

 - - intenif_map_iterator_create(ErlNifEnv *env, ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEntry entry) + + + intenif_map_iterator_create(ErlNifEnv *env, ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEntry entry) Create a map iterator

Create an iterator for the map map by initializing the structure pointed to by iter. The entry argument determines @@ -1477,42 +1655,66 @@ enif_map_iterator_destroy(env, &iter); - voidenif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter) + + + voidenif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter) Destroy a map iterator -

Destroy a map iterator created by + +

Destroy a map iterator created by enif_map_iterator_create. -

+

+ - intenif_map_iterator_get_pair(ErlNifEnv *env, ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM *value) + + + intenif_map_iterator_get_pair(ErlNifEnv *env, ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM *value) Get key and value at current map iterator position -

Get key and value terms at current map iterator position. + +

Get key and value terms at current map iterator position. On success set *key and *value and return true. Return false if the iterator is positioned at head (before first entry) - or tail (beyond last entry).

 + or tail (beyond last entry).

+ - intenif_map_iterator_is_head(ErlNifEnv *env, ErlNifMapIterator *iter) + + + intenif_map_iterator_is_head(ErlNifEnv *env, ErlNifMapIterator *iter) Check if map iterator is positioned before first -

Return true if map iterator iter is positioned - before first entry.

 + +

Return true if map iterator iter is positioned + before first entry.

+ - intenif_map_iterator_is_tail(ErlNifEnv *env, ErlNifMapIterator *iter) + + + intenif_map_iterator_is_tail(ErlNifEnv *env, ErlNifMapIterator *iter) Check if map iterator is positioned after last -

Return true if map iterator iter is positioned - after last entry.

 + +

Return true if map iterator iter is positioned + after last entry.

+ - intenif_map_iterator_next(ErlNifEnv *env, ErlNifMapIterator *iter) + + + intenif_map_iterator_next(ErlNifEnv *env, ErlNifMapIterator *iter) Increment map iterator to point to next entry -

Increment map iterator to point to next key-value entry. + +

Increment map iterator to point to next key-value entry. Return true if the iterator is now positioned at a valid key-value entry, or false if the iterator is positioned at the tail (beyond the last - entry).

 + entry).

+ - intenif_map_iterator_prev(ErlNifEnv *env, ErlNifMapIterator *iter) + + + intenif_map_iterator_prev(ErlNifEnv *env, ErlNifMapIterator *iter) Decrement map iterator to point to previous entry -

Decrement map iterator to point to previous key-value entry. + +

Decrement map iterator to point to previous key-value entry. Return true if the iterator is now positioned at a valid key-value entry, or false if the iterator is positioned at the head (before the first - entry).

 + entry).

+ @@ -1541,41 +1743,74 @@ enif_map_iterator_destroy(env, &iter); - ErlNifMutex *enif_mutex_create(char *name) + + ErlNifMutex * + enif_mutex_create(char *name) -

Same as erl_drv_mutex_create. -

+ +

Same as erl_drv_mutex_create. +

+ - voidenif_mutex_destroy(ErlNifMutex *mtx) + + + void + enif_mutex_destroy(ErlNifMutex *mtx) -

Same as erl_drv_mutex_destroy. -

+ +

Same as erl_drv_mutex_destroy. +

+ - voidenif_mutex_lock(ErlNifMutex *mtx) + + + void + enif_mutex_lock(ErlNifMutex *mtx) -

Same as erl_drv_mutex_lock. -

+ +

Same as erl_drv_mutex_lock. +

+ - intenif_mutex_trylock(ErlNifMutex *mtx) + + + int + enif_mutex_trylock(ErlNifMutex *mtx) -

Same as erl_drv_mutex_trylock. -

+ +

Same as erl_drv_mutex_trylock. +

+ - voidenif_mutex_unlock(ErlNifMutex *mtx) + + + void + enif_mutex_unlock(ErlNifMutex *mtx) -

Same as erl_drv_mutex_unlock. -

+ +

Same as erl_drv_mutex_unlock. +

+ - ERL_NIF_TERMenif_now_time(ErlNifEnv *env) + + + ERL_NIF_TERM + enif_now_time(ErlNifEnv *env) -

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

 + +

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

+ - ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, + + + ErlNifResourceType * + enif_open_resource_type(ErlNifEnv* env, const char* module_str, const char* name, ErlNifResourceDtor* dtor, ErlNifResourceFlags flags, ErlNifResourceFlags* tried) Create or takeover a resource type -

Create or takeover a resource type identified by the string + +

Create or takeover a resource type identified by the string name and give it the destructor function pointed to by dtor. Argument flags can have the following values:

@@ -1600,7 +1835,10 @@ enif_map_iterator_destroy(env, &iter); and upgrade.

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

This function works the same as erlang:port_command/2 @@ -1630,15 +1868,24 @@ enif_map_iterator_destroy(env, &iter);

See also: enif_get_local_port.

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

Return the pointer to the private data that was set by load, + +

Return the pointer to the private data that was set by load, reload or upgrade.

-

Was previously named enif_get_data.

 +

Was previously named enif_get_data.

+ - ERL_NIF_TERMenif_raise_exception(ErlNifEnv* env, ERL_NIF_TERM reason) + + + ERL_NIF_TERM + enif_raise_exception(ErlNifEnv* env, ERL_NIF_TERM reason) Raise a NIF error exception -

Create an error exception with the term reason to be returned from a NIF, + +

Create an error exception with the term reason to be returned from a NIF, and associate it with the environment env. Once a NIF or any function it calls invokes enif_raise_exception, the runtime ensures that the exception it creates is raised when the NIF returns, even if the NIF attempts to return a non-exception @@ -1647,71 +1894,130 @@ enif_map_iterator_destroy(env, &iter); to enif_is_exception, but not to any other NIF API function.

See also: enif_has_pending_exception - and enif_make_badarg.

 + and enif_make_badarg.

+ - intenif_realloc_binary(ErlNifBinary* bin, size_t size) + + + int + enif_realloc_binary(ErlNifBinary* bin, size_t size) Change the size of a binary -

Change the size of a binary bin. The source binary + +

Change the size of a binary bin. The source binary may be read-only, in which case it will be left untouched and a mutable copy is allocated and assigned to *bin. Return true on success, - false if memory allocation failed.

 + false if memory allocation failed.

+ - voidenif_release_binary(ErlNifBinary* bin) + + + void + enif_release_binary(ErlNifBinary* bin) Release a binary -

Release a binary obtained from enif_alloc_binary.

 + +

Release a binary obtained from enif_alloc_binary.

+ - voidenif_release_resource(void* obj) + + + void + enif_release_resource(void* obj) Release a resource object -

Remove a reference to resource object objobtained from + +

Remove a reference to resource object objobtained from enif_alloc_resource. The resource object will be destructed when the last reference is removed. Each call to enif_release_resource must correspond to a previous call to enif_alloc_resource or enif_keep_resource. References made by enif_make_resource - can only be removed by the garbage collector.

 + can only be removed by the garbage collector.

+ - ErlNifRWLock *enif_rwlock_create(char *name) + + + ErlNifRWLock * + enif_rwlock_create(char *name) -

Same as erl_drv_rwlock_create. -

+ +

Same as erl_drv_rwlock_create. +

+ - voidenif_rwlock_destroy(ErlNifRWLock *rwlck) + + + void + enif_rwlock_destroy(ErlNifRWLock *rwlck) -

Same as erl_drv_rwlock_destroy. -

+ +

Same as erl_drv_rwlock_destroy. +

+ - voidenif_rwlock_rlock(ErlNifRWLock *rwlck) + + + void + enif_rwlock_rlock(ErlNifRWLock *rwlck) -

Same as erl_drv_rwlock_rlock. -

+ +

Same as erl_drv_rwlock_rlock. +

+ - voidenif_rwlock_runlock(ErlNifRWLock *rwlck) + + + void + enif_rwlock_runlock(ErlNifRWLock *rwlck) -

Same as erl_drv_rwlock_runlock. -

+ +

Same as erl_drv_rwlock_runlock. +

+ - voidenif_rwlock_rwlock(ErlNifRWLock *rwlck) + + + void + enif_rwlock_rwlock(ErlNifRWLock *rwlck) -

Same as erl_drv_rwlock_rwlock. -

+ +

Same as erl_drv_rwlock_rwlock. +

+ - voidenif_rwlock_rwunlock(ErlNifRWLock *rwlck) + + + void + enif_rwlock_rwunlock(ErlNifRWLock *rwlck) -

Same as erl_drv_rwlock_rwunlock. -

+ +

Same as erl_drv_rwlock_rwunlock. +

+ - intenif_rwlock_tryrlock(ErlNifRWLock *rwlck) + + + int + enif_rwlock_tryrlock(ErlNifRWLock *rwlck) -

Same as erl_drv_rwlock_tryrlock. -

+ +

Same as erl_drv_rwlock_tryrlock. +

+ - intenif_rwlock_tryrwlock(ErlNifRWLock *rwlck) + + + int + enif_rwlock_tryrwlock(ErlNifRWLock *rwlck) -

Same as erl_drv_rwlock_tryrwlock. -

+ +

Same as erl_drv_rwlock_tryrwlock. +

+ - ERL_NIF_TERMenif_schedule_nif(ErlNifEnv* env, const char* fun_name, int flags, ERL_NIF_TERM (*fp)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]), int argc, const ERL_NIF_TERM argv[]) + + + ERL_NIF_TERM + enif_schedule_nif(ErlNifEnv* env, const char* fun_name, int flags, ERL_NIF_TERM (*fp)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]), int argc, const ERL_NIF_TERM argv[]) Schedule a NIF for execution

Schedule NIF fp to execute. This function allows an application to break up long-running @@ -1736,14 +2042,23 @@ enif_map_iterator_destroy(env, &iter); return value and use it for further operations.

 - ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid) + + + ErlNifPid * + enif_self(ErlNifEnv* caller_env, ErlNifPid* pid) Get the pid of the calling process -

Initialize the pid variable *pid to represent the - calling process. Return pid.

 + +

Initialize the pid variable *pid to represent the + calling process. Return pid.

+ - intenif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg) + + + int + enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg) Send a message to a process -

Send a message to a process.

+ +

Send a message to a process.

env The environment of the calling process. Must be NULL if and @@ -1772,13 +2087,20 @@ enif_map_iterator_destroy(env, &iter); erts-8.0 (OTP 19).

 - unsignedenif_sizeof_resource(void* obj) + + + unsigned + enif_sizeof_resource(void* obj) Get the byte size of a resource object -

Get the byte size of a resource object obj obtained by - enif_alloc_resource.

 + +

Get the byte size of a resource object obj obtained by + enif_alloc_resource.

+ - intenif_snprintf(char *str, size_t size, const char *format, ...) + + int + enif_snprintf(char *str, size_t size, const char *format, ...) Format strings and Erlang terms

Similar to snprintf but this format string also accepts "%T" which formats Erlang terms. @@ -1787,12 +2109,18 @@ enif_map_iterator_destroy(env, &iter); - voidenif_system_info(ErlNifSysInfo *sys_info_ptr, size_t size) + void + enif_system_info(ErlNifSysInfo *sys_info_ptr, size_t size) Get information about the Erlang runtime system -

Same as driver_system_info. -

+ +

Same as driver_system_info. +

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

Allocates a new binary with enif_alloc_binary @@ -1804,37 +2132,70 @@ enif_map_iterator_destroy(env, &iter);

- intenif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts) + + + int + enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts) -

Same as erl_drv_thread_create. -

+ +

Same as erl_drv_thread_create. +

+ - voidenif_thread_exit(void *resp) + + + void + enif_thread_exit(void *resp) -

Same as erl_drv_thread_exit. -

+ +

Same as erl_drv_thread_exit. +

+ - intenif_thread_join(ErlNifTid, void **respp) + + + int + enif_thread_join(ErlNifTid, void **respp) -

Same as erl_drv_thread_join . -

+ +

Same as erl_drv_thread_join . +

+ - ErlNifThreadOpts *enif_thread_opts_create(char *name) + + + ErlNifThreadOpts * + enif_thread_opts_create(char *name) -

Same as erl_drv_thread_opts_create. -

+ +

Same as erl_drv_thread_opts_create. +

+ - voidenif_thread_opts_destroy(ErlNifThreadOpts *opts) + + + void + enif_thread_opts_destroy(ErlNifThreadOpts *opts) -

Same as erl_drv_thread_opts_destroy. -

+ +

Same as erl_drv_thread_opts_destroy. +

+ - ErlNifTidenif_thread_self(void) + + + ErlNifTid + enif_thread_self(void) -

Same as erl_drv_thread_self. -

+ +

Same as erl_drv_thread_self. +

+ - intenif_thread_type(void) + + + int + enif_thread_type(void) Determine type of current thread

Determine the type of currently executing thread. A positive value @@ -1853,8 +2214,10 @@ enif_map_iterator_destroy(env, &iter); + - ErlNifTimeenif_time_offset(ErlNifTimeUnit time_unit) + ErlNifTime + enif_time_offset(ErlNifTimeUnit time_unit) Get current Time Offset @@ -1878,25 +2241,44 @@ enif_map_iterator_destroy(env, &iter); - intenif_tsd_key_create(char *name, ErlNifTSDKey *key) + + void * + enif_tsd_get(ErlNifTSDKey key) -

Same as erl_drv_tsd_key_create. -

+ +

Same as erl_drv_tsd_get. +

+ - voidenif_tsd_key_destroy(ErlNifTSDKey key) + + + int + enif_tsd_key_create(char *name, ErlNifTSDKey *key) -

Same as erl_drv_tsd_key_destroy. -

+ +

Same as erl_drv_tsd_key_create. +

+ - void *enif_tsd_get(ErlNifTSDKey key) + + + void + enif_tsd_key_destroy(ErlNifTSDKey key) -

Same as erl_drv_tsd_get. -

+ +

Same as erl_drv_tsd_key_destroy. +

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

Same as erl_drv_tsd_set. -

+ +

Same as erl_drv_tsd_set. +

+
diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml index 7841fdfd63..e2852ce49d 100644 --- a/erts/doc/src/erl_tracer.xml +++ b/erts/doc/src/erl_tracer.xml @@ -169,83 +169,38 @@ is important that it is both fast and side effect free.

- - Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result - Check if a trace event should be generated. - - TraceTag = trace_tag() - TracerState = term() - Tracee = tracee() - FirstTraceTerm = term() - Opts = trace_opts() - Result = ok - - -

This callback will be called when a tracepoint is triggered and - the Module:enabled/3 - callback returned trace. In it any side effects needed by - the tracer should be done. The tracepoint payload is located in - the TraceTerm. The content of the TraceTerm depends on which - TraceTag has been triggered. - The TraceTerm corresponds to the - fourth element in the trace tuples described in - erlang:trace/3. - If the trace tuple has five elements, the fifth element will be sent as - the extra value in the Opts maps.

- - - - Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result - Check if a sequence trace event should be generated. - - TracerState = term() - Label = term() - SeqTraceInfo = term() - Opts = trace_opts() - Result = ok - - -

The TraceTag seq_trace is handled a little bit - differently. There is not Tracee for seq_trace, instead the - Label associated with the seq_trace event is given. - For more info on what Label and SeqTraceInfo can be - see the seq_trace manual.

- - - Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result + Module:enabled_call(TraceTag, TracerState, Tracee) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_procs() + TraceTag = trace_tag_call() TracerState = term() Tracee = tracee() Result = trace | discard | remove

This callback will be called whenever a tracepoint with trace flag - procs + call | return_to is triggered.

-

If enabled_procs/3 is not defined enabled/3 will be called instead.

+

If enabled_call/3 is not defined enabled/3 will be called instead.

 - Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result + Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result Check if a trace event should be generated. - TraceTag = trace_tag() + TraceTag = trace_tag_gc() TracerState = term() Tracee = tracee() - FirstTraceTerm = term() - Opts = trace_opts() - Result = ok + Result = trace | discard | remove -

This callback will be called when a tracepoint is triggered and - the Module:enabled_procs/3 - callback returned trace.

-

If trace_procs/5 is not defined trace/5 will be called instead.

+

This callback will be called whenever a tracepoint with trace flag + garbage_collection + is triggered.

+

If enabled_garbage_collection/3 is not defined enabled/3 will be called instead.

 @@ -267,57 +222,36 @@ - Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result - Check if a trace event should be generated. - - TraceTag = trace_tag() - TracerState = term() - Tracee = tracee() - FirstTraceTerm = term() - Opts = trace_opts() - Result = ok - - -

This callback will be called when a tracepoint is triggered and - the Module:enabled_ports/3 - callback returned trace.

-

If trace_ports/5 is not defined trace/5 will be called instead.

- - - - - Module:enabled_running_procs(TraceTag, TracerState, Tracee) -> Result + Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_running_procs() + TraceTag = trace_tag_procs() TracerState = term() Tracee = tracee() Result = trace | discard | remove

This callback will be called whenever a tracepoint with trace flag - running_procs | running + procs is triggered.

-

If enabled_running_procs/3 is not defined enabled/3 will be called instead.

+

If enabled_procs/3 is not defined enabled/3 will be called instead.

 - Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result + Module:enabled_receive(TraceTag, TracerState, Tracee) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_running_procs() + TraceTag = trace_tag_receive() TracerState = term() Tracee = tracee() - FirstTraceTerm = term() - Opts = trace_opts() - Result = ok + Result = trace | discard | remove -

This callback will be called when a tracepoint is triggered and - the Module:enabled_running_procs/3 - callback returned trace.

-

If trace_running_procs/5 is not defined trace/5 will be called instead.

+

This callback will be called whenever a tracepoint with trace flag + 'receive' + is triggered.

+

If enabled_receive/3 is not defined enabled/3 will be called instead.

 @@ -339,41 +273,83 @@ - Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result + Module:enabled_running_procs(TraceTag, TracerState, Tracee) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_running_ports() + TraceTag = trace_tag_running_procs() TracerState = term() Tracee = tracee() - FirstTraceTerm = term() - Opts = trace_opts() - Result = ok + Result = trace | discard | remove -

This callback will be called when a tracepoint is triggered and - the Module:enabled_running_ports/3 - callback returned trace.

-

If trace_running_ports/5 is not defined trace/5 will be called instead.

+

This callback will be called whenever a tracepoint with trace flag + running_procs | running + is triggered.

+

If enabled_running_procs/3 is not defined enabled/3 will be called instead.

 - Module:enabled_call(TraceTag, TracerState, Tracee) -> Result + Module:enabled_send(TraceTag, TracerState, Tracee) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_call() + TraceTag = trace_tag_send() TracerState = term() Tracee = tracee() Result = trace | discard | remove

This callback will be called whenever a tracepoint with trace flag - call | return_to + send is triggered.

-

If enabled_call/3 is not defined enabled/3 will be called instead.

+

If enabled_send/3 is not defined enabled/3 will be called instead.

 + + Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result + Check if a trace event should be generated. + + TraceTag = trace_tag() + TracerState = term() + Tracee = tracee() + FirstTraceTerm = term() + Opts = trace_opts() + Result = ok + + +

This callback will be called when a tracepoint is triggered and + the Module:enabled/3 + callback returned trace. In it any side effects needed by + the tracer should be done. The tracepoint payload is located in + the TraceTerm. The content of the TraceTerm depends on which + TraceTag has been triggered. + The TraceTerm corresponds to the + fourth element in the trace tuples described in + erlang:trace/3. + If the trace tuple has five elements, the fifth element will be sent as + the extra value in the Opts maps.

+ + + + Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result + Check if a sequence trace event should be generated. + + TracerState = term() + Label = term() + SeqTraceInfo = term() + Opts = trace_opts() + Result = ok + + +

The TraceTag seq_trace is handled a little bit + differently. There is not Tracee for seq_trace, instead the + Label associated with the seq_trace event is given. + For more info on what Label and SeqTraceInfo can be + see the seq_trace manual.

+ + + Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result Check if a trace event should be generated. @@ -394,55 +370,59 @@ - Module:enabled_send(TraceTag, TracerState, Tracee) -> Result + Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_send() + TraceTag = trace_tag_gc() TracerState = term() Tracee = tracee() - Result = trace | discard | remove + FirstTraceTerm = term() + Opts = trace_opts() + Result = ok -

This callback will be called whenever a tracepoint with trace flag - send - is triggered.

-

If enabled_send/3 is not defined enabled/3 will be called instead.

+

This callback will be called when a tracepoint is triggered and + the Module:enabled_garbage_collection/3 + callback returned trace.

+

If trace_garbage_collection/5 is not defined trace/5 will be called instead.

 - Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result + Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_send() + TraceTag = trace_tag() TracerState = term() Tracee = tracee() FirstTraceTerm = term() Opts = trace_opts() - Result = ok + Result = ok

This callback will be called when a tracepoint is triggered and - the Module:enabled_send/3 + the Module:enabled_ports/3 callback returned trace.

-

If trace_send/5 is not defined trace/5 will be called instead.

+

If trace_ports/5 is not defined trace/5 will be called instead.

 - Module:enabled_receive(TraceTag, TracerState, Tracee) -> Result + Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_receive() + TraceTag = trace_tag() TracerState = term() Tracee = tracee() - Result = trace | discard | remove + FirstTraceTerm = term() + Opts = trace_opts() + Result = ok -

This callback will be called whenever a tracepoint with trace flag - 'receive' - is triggered.

-

If enabled_receive/3 is not defined enabled/3 will be called instead.

+

This callback will be called when a tracepoint is triggered and + the Module:enabled_procs/3 + callback returned trace.

+

If trace_procs/5 is not defined trace/5 will be called instead.

 @@ -466,27 +446,48 @@ - Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result + Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_gc() + TraceTag = trace_tag_running_ports() TracerState = term() Tracee = tracee() - Result = trace | discard | remove + FirstTraceTerm = term() + Opts = trace_opts() + Result = ok -

This callback will be called whenever a tracepoint with trace flag - garbage_collection - is triggered.

-

If enabled_garbage_collection/3 is not defined enabled/3 will be called instead.

+

This callback will be called when a tracepoint is triggered and + the Module:enabled_running_ports/3 + callback returned trace.

+

If trace_running_ports/5 is not defined trace/5 will be called instead.

 - Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result + Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result Check if a trace event should be generated. - TraceTag = trace_tag_gc() + TraceTag = trace_tag_running_procs() + TracerState = term() + Tracee = tracee() + FirstTraceTerm = term() + Opts = trace_opts() + Result = ok + + +

This callback will be called when a tracepoint is triggered and + the Module:enabled_running_procs/3 + callback returned trace.

+

If trace_running_procs/5 is not defined trace/5 will be called instead.

+ + + + + Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result + Check if a trace event should be generated. + + TraceTag = trace_tag_send() TracerState = term() Tracee = tracee() FirstTraceTerm = term() @@ -495,9 +496,9 @@

This callback will be called when a tracepoint is triggered and - the Module:enabled_garbage_collection/3 + the Module:enabled_send/3 callback returned trace.

-

If trace_garbage_collection/5 is not defined trace/5 will be called instead.

+

If trace_send/5 is not defined trace/5 will be called instead.

 diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 6289f033b2..cab18ac8b8 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -74,27 +74,33 @@ Supported time unit representations:

PartsPerSecond :: integer() >= 1 -

Time unit expressed in parts per second. That is, + +

Time unit expressed in parts per second. That is, the time unit equals 1/PartsPerSecond second.

 seconds -

Symbolic representation of the time unit + +

Symbolic representation of the time unit represented by the integer 1.

 milli_seconds -

Symbolic representation of the time unit + +

Symbolic representation of the time unit represented by the integer 1000.

 micro_seconds -

Symbolic representation of the time unit + +

Symbolic representation of the time unit represented by the integer 1000000.

 nano_seconds -

Symbolic representation of the time unit + +

Symbolic representation of the time unit represented by the integer 1000000000.

 native -

Symbolic representation of the native time unit + +

Symbolic representation of the native time unit used by the Erlang runtime system.

The native time unit is determined at @@ -131,7 +137,8 @@ perf_counter -

Symbolic representation of the performance counter + +

Symbolic representation of the performance counter time unit used by the Erlang runtime system.

The perf_counter time unit behaves much in the same way @@ -470,17 +477,6 @@ - - - Converts a bitstring to a list. - -

Returns a list of integers corresponding to the bytes of - Bitstring. If the number of bits in the binary - is not divisible by 8, the last element of the list is a bitstring - containing the remaining 1-7 bits.

- - - Decodes an Erlang external term format binary. @@ -546,6 +542,17 @@ + + + Converts a bitstring to a list. + +

Returns a list of integers corresponding to the bytes of + Bitstring. If the number of bits in the binary + is not divisible by 8, the last element of the list is a bitstring + containing the remaining 1-7 bits.

+ + + Increments the reduction counter. @@ -582,6 +589,16 @@ + + + Cancels a timer. + +

Cancels a timer. The same as calling + erlang:cancel_timer(TimerRef, + []).

+ + + Cancels a timer. @@ -676,15 +693,6 @@ erlang:read_timer/2.

 - - - Cancels a timer. - -

Cancels a timer. The same as calling - erlang:cancel_timer(TimerRef, - []).

- - Checks if a module has old code. @@ -935,14 +943,16 @@

The following options are available:

{packet_size, integer() >= 0} -

Sets the maximum allowed size of the packet body. + +

Sets the maximum allowed size of the packet body. If the packet header indicates that the length of the packet is longer than the maximum allowed length, the packet is considered invalid. Default is 0, which means no size limit.

 {line_length, integer() >= 0} -

For packet type line, lines longer than + +

For packet type line, lines longer than the indicated length are truncated.

Option line_length also applies to http* packet types as an alias for option packet_size @@ -950,7 +960,8 @@ only intended for backward compatibility.

 {line_delimiter, 0 =< byte() =< 255} -

For packet type line, sets the delimiting byte. + +

For packet type line, sets the delimiting byte. Default is the latin1 character $\n.

 @@ -1239,7 +1250,8 @@ b

The following behavior applies if Reason is any term, except normal or kill:

- If Pid is not trapping exits, + + If Pid is not trapping exits, Pid itself exits with exit reason Reason. @@ -1963,6 +1975,19 @@ os_prompt% + + + Size of an iolist. + +

Returns an integer that is the size in bytes + of the binary that would be the result of + iolist_to_binary(Item), for example:

+ 
+> iolist_size([1,2|<<3,4>>]).
+4
+ + + Converts an iolist to a binary. @@ -1981,19 +2006,6 @@ os_prompt% - - - Size of an iolist. - -

Returns an integer that is the size in bytes - of the binary that would be the result of - iolist_to_binary(Item), for example:

- 
-> iolist_size([1,2|<<3,4>>]).
-4
- - - Checks whether the local node is alive. @@ -3696,6 +3708,52 @@ os_prompt% + + + Performs a synchronous call to a port with term data. + +

Performs a synchronous call to a port. The meaning of + Operation and Data + depends on the port, that is, + on the port driver. Not all port drivers support this feature.

+

Port is a port identifier, + referring to a driver.

+

Operation is an integer, which is passed on to + the driver.

+

Data is any Erlang term. This data is converted + to binary term format and sent to the port.

+

Returns a term from the driver. The meaning of the returned + data also depends on the port driver.

+

Failures:

+ + badarg + + If Port is not an identifier of an open port, + or the registered name of an open port. If the calling + process was previously linked to the closed port, + identified by Port, the exit signal + from the port is guaranteed to be delivered before this + badarg exception occurs. + + badarg + + If Operation does not fit in a 32-bit integer. + + badarg + + If the port driver does not support synchronous control + operations. + + badarg + + If the port driver so decides for any reason (probably + something wrong with Operation + or Data). + + + + + Closes an open port. @@ -3951,52 +4009,6 @@ os_prompt% - - - Performs a synchronous call to a port with term data. - -

Performs a synchronous call to a port. The meaning of - Operation and Data - depends on the port, that is, - on the port driver. Not all port drivers support this feature.

-

Port is a port identifier, - referring to a driver.

-

Operation is an integer, which is passed on to - the driver.

-

Data is any Erlang term. This data is converted - to binary term format and sent to the port.

-

Returns a term from the driver. The meaning of the returned - data also depends on the port driver.

-

Failures:

- - badarg - - If Port is not an identifier of an open port, - or the registered name of an open port. If the calling - process was previously linked to the closed port, - identified by Port, the exit signal - from the port is guaranteed to be delivered before this - badarg exception occurs. - - badarg - - If Operation does not fit in a 32-bit integer. - - badarg - - If the port driver does not support synchronous control - operations. - - badarg - - If the port driver so decides for any reason (probably - something wrong with Operation - or Data). - - - - - Information about a port. @@ -4454,14 +4466,16 @@ os_prompt% are stored. When the flag is:

off_heap -

+ +

All messages in the message queue will be stored outside of the process heap. This implies that no messages in the message queue will be part of a garbage collection of the process.

on_heap -

+ +

All messages in the message queue will eventually be placed on heap. They may however temporarily be stored off heap. This is how messages always have been stored @@ -5125,6 +5139,15 @@ os_prompt% + + + Reads the state of a timer. + +

Read the state of a timer. The same as calling + erlang:read_timer(TimerRef, + []).

+ + Reads the state of a timer. @@ -5191,15 +5214,6 @@ os_prompt% erlang:cancel_timer/2.

 - - - Reads the state of a timer. - -

Read the state of a timer. The same as calling - erlang:read_timer(TimerRef, - []).

- - @@ -5369,6 +5383,15 @@ true + + + Starts a timer. + +

Starts a timer. The same as calling + erlang:send_after(Time, + Dest, Msg, []).

+ + Start a timer @@ -5382,15 +5405,6 @@ true erlang:start_timer/4.

 - - - Starts a timer. - -

Starts a timer. The same as calling - erlang:send_after(Time, - Dest, Msg, []).

- - @@ -5891,6 +5905,16 @@ true + + + Starts a timer. + +

Starts a timer. The same as calling + erlang:start_timer(Time, + Dest, Msg, []).

+ + + Starts a timer. @@ -5961,16 +5985,6 @@ true - - - Starts a timer. - -

Starts a timer. The same as calling - erlang:start_timer(Time, - Dest, Msg, []).

- - - Information about active processes and ports. @@ -6367,6 +6381,20 @@ ok + + + Suspends a process. + +

Suspends the process identified by + Suspendee. The same as calling + erlang:suspend_process(Suspendee, + []).

+ +

This BIF is intended for debugging only.

+ + + + Suspends a process. @@ -6468,20 +6496,6 @@ ok - - - Suspends a process. - -

Suspends the process identified by - Suspendee. The same as calling - erlang:suspend_process(Suspendee, - []).

- -

This BIF is intended for debugging only.

- - - - Sets system flag backtrace_depth. @@ -6750,39 +6764,48 @@ ok bound and can be any of the following:

unbound -

Same as command-line argument + +

Same as command-line argument +sbt u in erl(1).

no_spread -

Same as command-line argument + +

Same as command-line argument +sbt ns in erl(1).

thread_spread -

Same as command-line argument + +

Same as command-line argument +sbt ts in erl(1).

processor_spread -

Same as command-line argument + +

Same as command-line argument +sbt ps in erl(1).

spread -

Same as command-line argument + +

Same as command-line argument +sbt s in erl(1).

no_node_thread_spread -

Same as command-line argument + +

Same as command-line argument +sbt nnts in erl(1).

no_node_processor_spread -

Same as command-line argument + +

Same as command-line argument +sbt nnps in erl(1).

thread_no_node_processor_spread -

Same as command-line argument + +

Same as command-line argument +sbt tnnps in erl(1).

default_bind -

Same as command-line argument + +

Same as command-line argument +sbt db in erl(1).

@@ -6877,16 +6900,19 @@ ok is used, the time offset state is left unchanged.

Returns the old state identifier. That is:

-

If preliminary is returned, finalization was + +

If preliminary is returned, finalization was performed and the time offset is now final.

 -

If final is returned, the time offset was + +

If final is returned, the time offset was already in the final state. This either because another erlang:system_flag(time_offset, finalize) call, or because no time warp mode is used.

 -

If volatile is returned, the time offset + +

If volatile is returned, the time offset cannot be finalized because multi time warp mode is used.

 @@ -7468,7 +7494,8 @@ ok dtrace or systemtap).

 end_time -

The last Erlang monotonic + +

The last Erlang monotonic time in native time unit that can be represented internally in the current Erlang runtime system @@ -7695,18 +7722,21 @@ ok introduced in the future:

{function, Function} -

Function is the name of the function + +

Function is the name of the function used. This tuple always exist if OS monotonic time is available to the runtime system.

 {clock_id, ClockId} -

This tuple only exist if Function + +

This tuple only exist if Function can be used with different clocks. ClockId corresponds to the clock identifier used when calling Function.

 {resolution, OsMonotonicTimeResolution} -

Highest possible + +

Highest possible resolution of current OS monotonic time source as parts per second. If no resolution information can be retrieved @@ -7724,7 +7754,8 @@ ok OsMonotonicTimeResolution.

 {extended, Extended} -

Extended equals yes if + +

Extended equals yes if the range of time values has been extended; otherwise, Extended equals no. The range needs to be extended if Function @@ -7733,14 +7764,16 @@ ok value.

 {parallel, Parallel} -

Parallel equals yes if + +

Parallel equals yes if Function is called in parallel from multiple threads. If it is not called in parallel, because calls needs to be serialized, Parallel equals no.

 {time, OsMonotonicTime} -

OsMonotonicTime equals current OS + +

OsMonotonicTime equals current OS monotonic time in native time unit.

 @@ -7757,17 +7790,20 @@ ok introduced in the future:

{function, Function} -

Function is the name of the funcion - used.

 - + +

Function is the name of the funcion + used.

+ {clock_id, ClockId} -

This tuple only exist if Function + +

This tuple only exist if Function can be used with different clocks. ClockId corresponds to the clock identifier used when calling - Function.

 - + Function.

+ {resolution, OsSystemTimeResolution} -

Highest possible + +

Highest possible resolution of current OS system time source as parts per second. If no resolution information can be retrieved @@ -7782,19 +7818,22 @@ ok precision do align with the resolution. You do, however, know that the precision is not better than - OsSystemTimeResolution.

 - + OsSystemTimeResolution.

+ {parallel, Parallel} -

Parallel equals yes if + +

Parallel equals yes if Function is called in parallel from multiple threads. If it is not called in parallel, because calls needs to be serialized, Parallel equals - no.

 - + no.

+ {time, OsSystemTime} -

OsSystemTime equals current OS + +

OsSystemTime equals current OS system time in native - time unit.

 + time unit.

+ port_parallelism @@ -7930,7 +7969,8 @@ ok with SMP support, otherwise false is returned.

start_time -

The Erlang monotonic + +

The Erlang monotonic time in native time unit at the time when current Erlang runtime system instance started. See also @@ -7973,14 +8013,16 @@ ok

Returns the state of the time offset:

preliminary -

The time offset is preliminary, and will be changed + +

The time offset is preliminary, and will be changed at a later time when being finalized. The preliminary time offset is used during the preliminary phase of the single time warp mode.

 final -

The time offset is final. This either because + +

The time offset is final. This either because no time warp mode is used, or because the time offset have been finalized when @@ -7988,27 +8030,32 @@ ok time warp mode is used.

 volatile -

The time offset is volatile. That is, it can + +

The time offset is volatile. That is, it can change at any time. This is because multi time warp mode is used.

 time_warp_mode -

Returns a value identifying the + +

Returns a value identifying the time warp mode being used:

no_time_warp -

The no + +

The no time warp mode is used.

 single_time_warp -

The single + +

The single time warp mode is used.

 multi_time_warp -

The multi + +

The multi time warp mode is used.

 @@ -9704,42 +9751,6 @@ timestamp() -> - - - Current date and time according to Universal Time Coordinated (UTC). - -

Returns the current date and time according to Universal - Time Coordinated (UTC) in the form - {{Year, Month, Day}, {Hour, Minute, Second}} if - supported by the underlying OS. - Otherwise erlang:universaltime() is equivalent to - erlang:localtime().

-

Example:

- 
-> erlang:universaltime().
-{{1996,11,6},{14,18,43}}
- - - - - - Converts from Universal Time Coordinated (UTC) to local date and time. - -

Converts Universal Time Coordinated (UTC) date and time to - local date and time in the form - {{Year, Month, Day}, {Hour, Minute, Second}} if - supported by the underlying OS. - Otherwise no conversion is done, and - Universaltime is returned.

-

Example:

- 
-> erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
-{{1996,11,7},{15,18,43}}
-

Failure: badarg if Universaltime denotes - an invalid date and time.

- - - Get a unique integer value @@ -9778,14 +9789,16 @@ timestamp() -> positive -

Return only positive integers.

+ +

Return only positive integers.

Note that by passing the positive modifier you will get heap allocated integers (bignums) quicker.

 monotonic -

Return + +

Return strictly monotonically increasing integers corresponding to creation time. That is, the integer @@ -9834,6 +9847,43 @@ timestamp() -> + + + + Current date and time according to Universal Time Coordinated (UTC). + +

Returns the current date and time according to Universal + Time Coordinated (UTC) in the form + {{Year, Month, Day}, {Hour, Minute, Second}} if + supported by the underlying OS. + Otherwise erlang:universaltime() is equivalent to + erlang:localtime().

+

Example:

+ 
+> erlang:universaltime().
+{{1996,11,6},{14,18,43}}
+ + + + + + Converts from Universal Time Coordinated (UTC) to local date and time. + +

Converts Universal Time Coordinated (UTC) date and time to + local date and time in the form + {{Year, Month, Day}, {Hour, Minute, Second}} if + supported by the underlying OS. + Otherwise no conversion is done, and + Universaltime is returned.

+

Example:

+ 
+> erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
+{{1996,11,7},{15,18,43}}
+

Failure: badarg if Universaltime denotes + an invalid date and time.

+ + + Removes a link to another process or port. diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml index 861661043f..a3c94e4a7f 100644 --- a/erts/doc/src/zlib.xml +++ b/erts/doc/src/zlib.xml @@ -106,10 +106,36 @@ list_to_binary([Compressed|Last]) - - Open a stream and return a stream reference + + Calculate the adler checksum -

Open a zlib stream.

+

Calculate the Adler-32 checksum for Data.

+ + + + + Calculate the adler checksum + +

Update a running Adler-32 checksum for Data. + If Data is the empty binary or the empty iolist, this function returns + the required initial value for the checksum.

+ 
+Crc = lists:foldl(fun(Data,Crc0) ->
+                      zlib:adler32(Z, Crc0, Data),
+                  end, zlib:adler32(Z,<< >>), Datas)
+ + + + + Combine two Adler-32 checksums + +

Combine two Adler-32 checksums into one. For two binaries or iolists, + Data1 and Data2 with sizes of Size1 and + Size2, with Adler-32 checksums Adler1 and + Adler2. adler32_combine/4 returns the Adler + checksum of [Data1,Data2], requiring + only Adler1, Adler2, and Size2. +

@@ -119,6 +145,108 @@ list_to_binary([Compressed|Last])

Closes the stream referenced by Z.

 + + + Compress data with standard zlib functionality + +

Compress data (with zlib headers and checksum).

+ + + + + Get current CRC + +

Get the current calculated CRC checksum.

+ + + + + Calculate CRC + +

Calculate the CRC checksum for Data.

+ + + + + Calculate CRC + +

Update a running CRC checksum for Data. + If Data is the empty binary or the empty iolist, this function returns + the required initial value for the crc.

+ 
+Crc = lists:foldl(fun(Data,Crc0) ->
+                      zlib:crc32(Z, Crc0, Data),
+                  end, zlib:crc32(Z,<< >>), Datas)
+ + + + + Combine two CRC's + +

Combine two CRC checksums into one. For two binaries or iolists, + Data1 and Data2 with sizes of Size1 and + Size2, with CRC checksums CRC1 and + CRC2. crc32_combine/4 returns the CRC + checksum of [Data1,Data2], requiring + only CRC1, CRC2, and Size2. +

+ + + + + + Compress data + +

Same as deflate(Z, Data, none).

+ + + + + Compress data + +

deflate/3 compresses as much data as possible, and + stops when the input buffer becomes empty. It may introduce + some output latency (reading input without producing any + output) except when forced to flush.

+

If the parameter Flush is set to sync, all + pending output is flushed to the output buffer and the + output is aligned on a byte boundary, so that the + decompressor can get all input data available so far. + Flushing may degrade compression for some compression algorithms and so + it should be used only when necessary.

+

If Flush is set to full, all output is flushed as with + sync, and the compression state is reset so that decompression can + restart from this point if previous compressed data has been damaged or if + random access is desired. Using full too often can seriously degrade + the compression.

+

If the parameter Flush is set to finish, + pending input is processed, pending output is flushed and + deflate/3 returns. Afterwards the only possible + operations on the stream are deflateReset/1 or deflateEnd/1.

+

Flush can be set to finish immediately after + deflateInit if all compression is to be done in one step.

+ 
+ 
+zlib:deflateInit(Z),
+B1 = zlib:deflate(Z,Data),
+B2 = zlib:deflate(Z,<< >>,finish),
+zlib:deflateEnd(Z),
+list_to_binary([B1,B2])
+ + + + + + End deflate session + +

End the deflate session and cleans all data used. + Note that this function will throw an data_error + exception if the last call to + deflate/3 was not called with Flush set to + finish.

+ + + Initialize a session for compression @@ -181,44 +309,32 @@ list_to_binary([Compressed|Last]) - - Compress data + + Dynamicly update deflate parameters -

Same as deflate(Z, Data, none).

+

Dynamically update the compression level and compression + strategy. The interpretation of Level and + Strategy is as in deflateInit/6. This can be + used to switch between compression and straight copy of the + input data, or to switch to a different kind of input data + requiring a different strategy. If the compression level is + changed, the input available so far is compressed with the + old level (and may be flushed); the new level will take + effect only at the next call of deflate/3.

+

Before the call of deflateParams, the stream state must be set as for + a call of deflate/3, since the currently available input may have to + be compressed and flushed.

 - - Compress data + + Reset the deflate session -

deflate/3 compresses as much data as possible, and - stops when the input buffer becomes empty. It may introduce - some output latency (reading input without producing any - output) except when forced to flush.

-

If the parameter Flush is set to sync, all - pending output is flushed to the output buffer and the - output is aligned on a byte boundary, so that the - decompressor can get all input data available so far. - Flushing may degrade compression for some compression algorithms and so - it should be used only when necessary.

-

If Flush is set to full, all output is flushed as with - sync, and the compression state is reset so that decompression can - restart from this point if previous compressed data has been damaged or if - random access is desired. Using full too often can seriously degrade - the compression.

-

If the parameter Flush is set to finish, - pending input is processed, pending output is flushed and - deflate/3 returns. Afterwards the only possible - operations on the stream are deflateReset/1 or deflateEnd/1.

-

Flush can be set to finish immediately after - deflateInit if all compression is to be done in one step.

- 
- 
-zlib:deflateInit(Z),
-B1 = zlib:deflate(Z,Data),
-B2 = zlib:deflate(Z,<< >>,finish),
-zlib:deflateEnd(Z),
-list_to_binary([B1,B2])
+

This function is equivalent to deflateEnd/1 + followed by deflateInit/[1|2|6], but does not free + and reallocate all the internal compression state. The + stream will keep the same compression level and any other + attributes.

 @@ -236,66 +352,24 @@ list_to_binary([B1,B2]) - - Reset the deflate session - -

This function is equivalent to deflateEnd/1 - followed by deflateInit/[1|2|6], but does not free - and reallocate all the internal compression state. The - stream will keep the same compression level and any other - attributes.

- - - - - Dynamicly update deflate parameters - -

Dynamically update the compression level and compression - strategy. The interpretation of Level and - Strategy is as in deflateInit/6. This can be - used to switch between compression and straight copy of the - input data, or to switch to a different kind of input data - requiring a different strategy. If the compression level is - changed, the input available so far is compressed with the - old level (and may be flushed); the new level will take - effect only at the next call of deflate/3.

-

Before the call of deflateParams, the stream state must be set as for - a call of deflate/3, since the currently available input may have to - be compressed and flushed.

- - - - - End deflate session + + Get buffer size -

End the deflate session and cleans all data used. - Note that this function will throw an data_error - exception if the last call to - deflate/3 was not called with Flush set to - finish.

+

Get the size of intermediate buffer.

 - - Initialize a session for decompression + + Uncompress data with gz header -

Initialize a zlib stream for decompression.

+

Uncompress data (with gz headers and checksum).

 - - Initialize a session for decompression + + Compress data with gz header -

Initialize decompression session on zlib stream.

-

The WindowBits parameter is the base two logarithm - of the maximum window size (the size of the history buffer). - It should be in the range 8 through 15. - The default value is 15 if inflateInit/1 is used. - If a compressed stream with a larger window size is - given as input, inflate() will throw the data_error - exception. A negative WindowBits value makes zlib ignore the - zlib header (and checksum) from the stream. Note that the zlib - source mentions this only as a undocumented feature.

+

Compress data (with gz headers and checksum).

 @@ -312,6 +386,16 @@ list_to_binary([B1,B2]) compressor.

 + + + Read next uncompressed chunk + +

Read next chunk of uncompressed data, initialized by + inflateChunk/2.

+

This function should be repeatedly called, while it returns + {more, Decompressed}.

+ + Decompress data with limited output size @@ -350,13 +434,46 @@ loop(Z, Handler, Uncompressed) -> - - Read next uncompressed chunk + + End inflate session -

Read next chunk of uncompressed data, initialized by - inflateChunk/2.

-

This function should be repeatedly called, while it returns - {more, Decompressed}.

+

End the inflate session and cleans all data used. Note + that this function will throw a data_error exception + if no end of stream was found (meaning that not all data + has been uncompressed).

+ + + + + Initialize a session for decompression + +

Initialize a zlib stream for decompression.

+ + + + + Initialize a session for decompression + +

Initialize decompression session on zlib stream.

+

The WindowBits parameter is the base two logarithm + of the maximum window size (the size of the history buffer). + It should be in the range 8 through 15. + The default value is 15 if inflateInit/1 is used. + If a compressed stream with a larger window size is + given as input, inflate() will throw the data_error + exception. A negative WindowBits value makes zlib ignore the + zlib header (and checksum) from the stream. Note that the zlib + source mentions this only as a undocumented feature.

+ + + + + >Reset the inflate session + +

This function is equivalent to inflateEnd/1 followed + by inflateInit/1, but does not free and reallocate all + the internal decompression state. The stream will keep + attributes that may have been set by inflateInit/[1|2].

 @@ -384,23 +501,10 @@ unpack(Z, Compressed, Dict) -> - - >Reset the inflate session - -

This function is equivalent to inflateEnd/1 followed - by inflateInit/1, but does not free and reallocate all - the internal decompression state. The stream will keep - attributes that may have been set by inflateInit/[1|2].

- - - - - End inflate session + + Open a stream and return a stream reference -

End the inflate session and cleans all data used. Note - that this function will throw a data_error exception - if no end of stream was found (meaning that not all data - has been uncompressed).

+

Open a zlib stream.

 @@ -410,93 +514,6 @@ unpack(Z, Compressed, Dict) ->

Sets the intermediate buffer size.

 - - - Get buffer size - -

Get the size of intermediate buffer.

- - - - - Get current CRC - -

Get the current calculated CRC checksum.

- - - - - Calculate CRC - -

Calculate the CRC checksum for Data.

- - - - - Calculate CRC - -

Update a running CRC checksum for Data. - If Data is the empty binary or the empty iolist, this function returns - the required initial value for the crc.

- 
-Crc = lists:foldl(fun(Data,Crc0) ->
-                      zlib:crc32(Z, Crc0, Data),
-                  end, zlib:crc32(Z,<< >>), Datas)
- - - - - Combine two CRC's - -

Combine two CRC checksums into one. For two binaries or iolists, - Data1 and Data2 with sizes of Size1 and - Size2, with CRC checksums CRC1 and - CRC2. crc32_combine/4 returns the CRC - checksum of [Data1,Data2], requiring - only CRC1, CRC2, and Size2. -

- - - - - Calculate the adler checksum - -

Calculate the Adler-32 checksum for Data.

- - - - - Calculate the adler checksum - -

Update a running Adler-32 checksum for Data. - If Data is the empty binary or the empty iolist, this function returns - the required initial value for the checksum.

- 
-Crc = lists:foldl(fun(Data,Crc0) ->
-                      zlib:adler32(Z, Crc0, Data),
-                  end, zlib:adler32(Z,<< >>), Datas)
- - - - - Combine two Adler-32 checksums - -

Combine two Adler-32 checksums into one. For two binaries or iolists, - Data1 and Data2 with sizes of Size1 and - Size2, with Adler-32 checksums Adler1 and - Adler2. adler32_combine/4 returns the Adler - checksum of [Data1,Data2], requiring - only Adler1, Adler2, and Size2. -

- - - - - Compress data with standard zlib functionality - -

Compress data (with zlib headers and checksum).

- - Uncompress data with standard zlib functionality @@ -504,13 +521,6 @@ Crc = lists:foldl(fun(Data,Crc0) ->

Uncompress data (with zlib headers and checksum).

 - - - Compress data without the zlib headers - -

Compress data (without zlib headers and checksum).

- - Uncompress data without the zlib headers @@ -519,17 +529,10 @@ Crc = lists:foldl(fun(Data,Crc0) -> - - Compress data with gz header - -

Compress data (with gz headers and checksum).

- - - - - Uncompress data with gz header + + Compress data without the zlib headers -

Uncompress data (with gz headers and checksum).

+

Compress data (without zlib headers and checksum).

 -- cgit v1.2.3