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 ++++++++++++++++++++++--------------------- 1 file changed, 1615 insertions(+), 1558 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') 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 -- cgit v1.2.3 From 57c3246511434f42214e113b8902af10ab9cca49 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Tue, 21 Jun 2016 15:50:34 +0200 Subject: erts: Editorial changes --- erts/doc/src/erl_driver.xml | 4206 +++++++++++++++++++++---------------------- 1 file changed, 2101 insertions(+), 2105 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index d8116d4650..69c3375858 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -21,7 +21,6 @@ limitations under the License. - erl_driver Jakob Cederlund Jakob Cederlund @@ -33,519 +32,546 @@ erl_driver.xml erl_driver - API functions for an Erlang driver + API functions for an Erlang driver.

An Erlang driver is a library containing a set of native driver - callback functions that the Erlang VM calls when certain - events occur. There may be multiple instances of a driver, each + callback functions that the Erlang Virtual Machine calls when certain + events occur. There can be multiple instances of a driver, each instance is associated with an Erlang port.

+ -

Use this functionality with extreme care!

+ +

Use this functionality with extreme care.

A driver callback is executed as a direct extension of the - native code of the VM. Execution is not made in a safe environment. - The VM can not provide the same services as provided when - executing Erlang code, such as preemptive scheduling or memory - protection. If the driver callback function doesn't behave well, - the whole VM will misbehave.

- -

A driver callback that crash will crash the whole VM.

 -

An erroneously implemented driver callback might cause - a VM internal state inconsistency which may cause a crash of the VM, - or miscellaneous misbehaviors of the VM at any point after the call - to the driver callback.

 -

A driver callback that do lengthy - work before returning will degrade responsiveness of the VM, - and may cause miscellaneous strange behaviors. Such strange behaviors - include, but are not limited to, extreme memory usage, and bad load - balancing between schedulers. Strange behaviors that might occur due - to lengthy work may also vary between OTP releases.

 + native code of the VM. Execution is not made in a safe environment. + The VM cannot provide the same services as provided when + executing Erlang code, such as pre-emptive scheduling or memory + protection. If the driver callback function does not behave well, + the whole VM will misbehave.

+ + +

A driver callback that crash will crash the whole VM.

+ + +

An erroneously implemented driver callback can cause a VM + internal state inconsistency, which can cause a crash of the VM, + or miscellaneous misbehaviors of the VM at any point after the + call to the driver callback.

+ + +

A driver callback doing + lengthy work before + returning degrades responsiveness of the VM and can cause + miscellaneous strange behaviors. Such strange behaviors + include, but are not limited to, extreme memory usage and bad + load balancing between schedulers. Strange behaviors that can + occur because of lengthy work can also vary between Erlang/OTP + releases.

+ - -

As of erts version 5.5.3 the driver interface has been extended - (see extended marker). - The extended interface introduce + + +

As from ERTS 5.5.3 the driver interface has been extended + (see + extended marker). The extended interface introduces version management, - the possibility to pass capability flags - (see driver flags) - to the runtime system at driver initialization, and some new - driver API functions.

+ the possibility to pass capability flags (see + + driver_flags) to the runtime system at driver + initialization, and some new driver API functions.

+ -

As of erts version 5.9 old drivers have to be recompiled - and have to use the extended interface. They also have to be - adjusted to the - 64-bit capable driver interface. - -

+

As from ERTS 5.9 old drivers must be recompiled + and use the extended interface. They must also be adjusted to the + + 64-bit capable driver interface.

 +

The driver calls back to the emulator, using the API functions declared in erl_driver.h. They are used for - outputting data from the driver, using timers, etc.

+ outputting data from the driver, using timers, and so on.

+

Each driver instance is associated with a port. Every port has a port owner process. Communication with the port is normally done through the port owner process. Most of the functions take the port handle as an argument. This identifies the driver - instance. Note that this port handle must be stored by the driver, + instance. Notice that this port handle must be stored by the driver, it is not given when the driver is called from the emulator (see - driver_entry).

+ + driver_entry).

+

Some of the functions take a parameter of type - ErlDrvBinary, a driver binary. It should be both + ErlDrvBinary, a driver binary. It is to be both allocated and freed by the caller. Using a binary directly avoids one extra copying of data.

+

Many of the output functions have a "header buffer", with hbuf and hlen parameters. This buffer is sent as a list before the binary (or list, depending on port mode) that is sent. This is convenient when matching on messages received from - the port. (Although in the latest versions of Erlang, there is - the binary syntax, that enables you to match on the beginning of + the port. (Although in the latest Erlang versions there is + the binary syntax, which enables you to match on the beginning of a binary.) - -

+ +

In the runtime system with SMP support, drivers are locked either on driver level or port level (driver instance level). By default - driver level locking will be used, i.e., only one emulator thread + driver level locking will be used, that is, only one emulator thread will execute code in the driver at a time. If port level locking - is used, multiple emulator threads may execute code in the driver - at the same time. There will only be one thread at a time calling - driver call-backs corresponding to the same port, though. In order - to enable port level locking set the ERL_DRV_FLAG_USE_PORT_LOCKING + is used, multiple emulator threads can execute code in the driver + at the same time. Only one thread at a time will call + driver callbacks corresponding to the same port, though. + To enable port level locking, set the ERL_DRV_FLAG_USE_PORT_LOCKING driver flag in - the driver_entry - used by the driver. When port level locking is used it is the - responsibility of the driver writer to synchronize all accesses + the driver_entry + used by the driver. When port level locking is used, + the driver writer is responsible for synchronizing all accesses to data shared by the ports (driver instances).

+

Most drivers written before the runtime system with SMP - support existed will be able to run in the runtime system - with SMP support without being rewritten if driver + support existed can run in the runtime system + with SMP support, without being rewritten, if driver level locking is used.

+

It is assumed that drivers do not access other drivers. If - drivers should access each other they have to provide their own - mechanism for thread safe synchronization. Such "inter driver + drivers access each other, they must provide their own + mechanism for thread-safe synchronization. Such "inter-driver communication" is strongly discouraged.

 +

Previously, in the runtime system without SMP support, - specific driver call-backs were always called from the same + specific driver callbacks were always called from the same thread. This is not the case in the runtime system with SMP support. Regardless of locking scheme used, calls - to driver call-backs may be made from different threads, e.g., - two consecutive calls to exactly the same call-back for exactly - the same port may be made from two different threads. This - will for most drivers not be a problem, but it might. - Drivers that depend on all call-backs being called in the - same thread, have to be rewritten before being used + to driver callbacks can be made from different threads. For example, + two consecutive calls to exactly the same callback for exactly + the same port can be made from two different threads. This + is for most drivers not a problem, but it can be. + Drivers that depend on all callbacks that are called in the + same thread, must be rewritten before they are used in the runtime system with SMP support.

+

Regardless of locking scheme used, calls to driver - call-backs may be made from different threads.

+ callbacks can be made from different threads.

 -

Most functions in this API are not thread-safe, i.e., - they may not be called from an arbitrary thread. Functions - that are not documented as thread-safe may only be called from - driver call-backs or function calls descending from a driver - call-back call. Note that driver call-backs may be called from + +

Most functions in this API are not thread-safe, that is, + they cannot be called from any thread. Functions + that are not documented as thread-safe can only be called from + driver callbacks or function calls descending from a driver + callback call. Notice that driver callbacks can be called from different threads. This, however, is not a problem for any - function in this API, since the emulator has control over + function in this API, as the emulator has control over these threads.

+ -

Functions not explicitly documented as thread safe are - not thread safe. Also note that some functions - are only thread safe when used in a runtime +

Functions not explicitly documented as thread-safe are + not thread safe. Also notice that some functions + are only thread-safe when used in a runtime system with SMP support.

-

A function not explicitly documented as thread safe may at - some point in time have a thread safe implementation in the - runtime system. Such an implementation may however change to - a thread unsafe implementation at any time without - any notice at all. -

-

Only use functions explicitly documented as thread safe - from arbitrary threads.

+

A function not explicitly documented as thread-safe can, at + some point in time, have a thread-safe implementation in the + runtime system. Such an implementation can however change to + a thread unsafe implementation at any time without + any notice.

+

Only use functions explicitly documented as thread-safe + from arbitrary threads.

 -

- As mentioned in the warning text at - the beginning of this document it is of vital importance that a driver callback - does return relatively fast. It is hard to give an exact maximum amount - of time that a driver callback is allowed to work, but as a rule of thumb - a well behaving driver callback should return before a millisecond has - passed. This can be achieved using different approaches. - If you have full control over the code that are to execute in the driver - callback, the best approach is to divide the work into multiple chunks of - work and trigger multiple calls to the - timeout callback using - zero timeouts. The - erl_drv_consume_timeslice() - function can be useful in order to determine when to trigger such - timeout callback calls. It might, however, not always be possible to - implement it this way, e.g. when calling third party libraries. In this - case you typically want to dispatch the work to another thread. - Information about thread primitives can be found below.

+ +

+ As mentioned in the warning text at + the beginning of this section, it is of vital importance that a driver + callback returns relatively fast. It is difficult to give an exact + maximum amount of time that a driver callback is allowed to work, but + usually a well-behaving driver callback is to return within 1 millisecond. + This can be achieved using different approaches. + If you have full control over the code to execute in the driver + callback, the best approach is to divide the work into multiple chunks of + work, and trigger multiple calls to the + time-out callback using + zero time-outs. Function + erl_drv_consume_timeslice can be useful to + determine when to trigger such time-out callback calls. However, sometimes + it cannot be implemented this way, for example when calling + third-party libraries. In this case, you typically want to dispatch the + work to another thread. Information about thread primitives is provided + below.
- FUNCTIONALITY + Functionality

All functions that a driver needs to do with Erlang are - performed through driver API functions. There are functions + performed through driver API functions. Functions exist for the following functionality:

+ Timer functions - Timer functions are used to control the timer that a driver - may use. The timer will have the emulator call the - timeout entry - function after a specified time. Only one timer is available - for each driver instance. + +

Control the timer that a driver can use. The timer has the + emulator call the + timeout entry function after a specified time. + Only one timer is available for each driver instance.

+ Queue handling

Every driver instance has an associated queue. This queue is a - SysIOVec that works as a buffer. It's mostly used for - the driver to buffer data that should be written to a device, + SysIOVec, which works as a buffer. It is mostly used for + the driver to buffer data that is to be written to a device, it is a byte stream. If the port owner process closes the - driver, and the queue is not empty, the driver will not be + driver, and the queue is not empty, the driver is not closed. This enables the driver to flush its buffers before closing.

-

The queue can be manipulated from arbitrary threads if - a port data lock is used. See documentation of the - ErlDrvPDL type for - more information.

+

The queue can be manipulated from any threads if + a port data lock is used. For more information, see + ErlDrvPDL.

 Output functions - With the output functions, the driver sends data back to - the emulator. They will be received as messages by the port owner - process, see open_port/2. The vector function and the - function taking a driver binary are faster, because they avoid - copying the data buffer. There is also a fast way of sending - terms from the driver, without going through the binary term - format. + +

With these functions, the driver sends data back to the emulator. + The data is received as messages by the port owner process, see + + erlang:open_port/2. The vector function and the + function taking a driver binary are faster, as they avoid + copying the data buffer. There is also a fast way of sending + terms from the driver, without going through the binary term + format.

 Failure - The driver can exit and signal errors up to Erlang. This is - only for severe errors, when the driver can't possibly keep - open. + +

The driver can exit and signal errors up to Erlang. This is + only for severe errors, when the driver cannot possibly keep + open.

+ Asynchronous calls - The latest Erlang versions (R7B and later) has provision for - asynchronous function calls, using a thread pool provided by - Erlang. There is also a select call, that can be used for - asynchronous drivers. + +

Erlang/OTP R7B and later versions have provision for + asynchronous function calls, using a thread pool provided by + Erlang. There is also a select call, which can be used for + asynchronous drivers.

+ Multi-threading -

A POSIX thread like API for multi-threading is provided. The - Erlang driver thread API only provide a subset of the functionality - provided by the POSIX thread API. The subset provided is - more or less the basic functionality needed for multi-threaded - programming: -

- - Threads - Mutexes - Condition variables - Read/Write locks - Thread specific data - -

The Erlang driver thread API can be used in conjunction with - the POSIX thread API on UN-ices and with the Windows native thread - API on Windows. The Erlang driver thread API has the advantage of - being portable, but there might exist situations where you want to - use functionality from the POSIX thread API or the Windows - native thread API. -

-

The Erlang driver thread API only returns error codes when it is - reasonable to recover from an error condition. If it isn't reasonable - to recover from an error condition, the whole runtime system is - terminated. For example, if a create mutex operation fails, an error - code is returned, but if a lock operation on a mutex fails, the - whole runtime system is terminated. -

-

Note that there exists no "condition variable wait with timeout" in - the Erlang driver thread API. This is due to issues with - pthread_cond_timedwait(). When the system clock suddenly - is changed, it isn't always guaranteed that you will wake up from - the call as expected. An Erlang runtime system has to be able to - cope with sudden changes of the system clock. Therefore, we have - omitted it from the Erlang driver thread API. In the Erlang driver - case, timeouts can and should be handled with the timer functionality - of the Erlang driver API. -

-

In order for the Erlang driver thread API to function, thread - support has to be enabled in the runtime system. An Erlang driver - can check if thread support is enabled by use of - driver_system_info(). - Note that some functions in the Erlang driver API are thread-safe - only when the runtime system has SMP support, also this - information can be retrieved via - driver_system_info(). - Also note that a lot of functions in the Erlang driver API are - not thread-safe regardless of whether SMP support is - enabled or not. If a function isn't documented as thread-safe it - is not thread-safe. -

-

NOTE: When executing in an emulator thread, it is - very important that you unlock all locks you - have locked before letting the thread out of your control; - otherwise, you are very likely to deadlock the whole - emulator. If you need to use thread specific data in an emulator - thread, only have the thread specific data set while the thread is - under your control, and clear the thread specific data before - you let the thread out of your control. -

-

In the future there will probably be debug functionality - integrated with the Erlang driver thread API. All functions - that create entities take a name argument. Currently - the name argument is unused, but it will be used when - the debug functionality has been implemented. If you name all - entities created well, the debug functionality will be able - to give you better error reports. -

+

A POSIX thread like API for multi-threading is provided. The + Erlang driver thread API only provides a subset of the functionality + provided by the POSIX thread API. The subset provided is + more or less the basic functionality needed for multi-threaded + programming:

+ + Threads + Mutexes + + Condition variables + + Read/write locks + + Thread-specific data + +

The Erlang driver thread API can be used in conjunction with + the POSIX thread API on UN-ices and with the Windows native thread + API on Windows. The Erlang driver thread API has the advantage of + being portable, but there can exist situations where you want to + use functionality from the POSIX thread API or the Windows + native thread API.

+

The Erlang driver thread API only returns error codes when it is + reasonable to recover from an error condition. If it is not reasonable + to recover from an error condition, the whole runtime system is + terminated. For example, if a create mutex operation fails, an error + code is returned, but if a lock operation on a mutex fails, the + whole runtime system is terminated.

+

Notice that there is no "condition variable wait with time-out" in + the Erlang driver thread API. This because of issues with + pthread_cond_timedwait. When the system clock suddenly + is changed, it is not always guaranteed that you will wake up from + the call as expected. An Erlang runtime system must be able to + cope with sudden changes of the system clock. Therefore, we have + omitted it from the Erlang driver thread API. In the Erlang driver + case, time-outs can and are to be handled with the timer functionality + of the Erlang driver API.

+

In order for the Erlang driver thread API to function, thread + support must be enabled in the runtime system. An Erlang driver + can check if thread support is enabled by use of + + driver_system_info. + Notice that some functions in the Erlang driver API are thread-safe + only when the runtime system has SMP support, also this + information can be retrieved through + + driver_system_info. + Also notice that many functions in the Erlang driver API are + not thread-safe, regardless of whether SMP support is + enabled or not. If a function is not documented as thread-safe, it + is not thread-safe.

+ +

When executing in an emulator thread, it is + very important that you unlock all locks you + have locked before letting the thread out of your control; + otherwise you are very likely to deadlock the whole + emulator.

+

If you need to use thread-specific data in an emulator + thread, only have the thread-specific data set while the thread is + under your control, and clear the thread-specific data before + you let the thread out of your control.

+ +

In the future, debug functionality will probably be + integrated with the Erlang driver thread API. All functions + that create entities take a name argument. Currently + the name argument is unused, but it will be used when + the debug functionality is implemented. If you name all + entities created well, the debug functionality will be able + to give you better error reports.

+ + Adding/removing drivers + +

A driver can add and later remove drivers.

 - Adding / removing drivers -

A driver can add and later remove drivers.

 Monitoring processes -

A driver can monitor a process that does not own a port.

 + +

A driver can monitor a process that does not own a port.

+ Version management

Version management is enabled for drivers that have set the - extended_marker - field of their - driver_entry - to ERL_DRV_EXTENDED_MARKER. erl_driver.h defines - ERL_DRV_EXTENDED_MARKER, - ERL_DRV_EXTENDED_MAJOR_VERSION, and - ERL_DRV_EXTENDED_MINOR_VERSION. - ERL_DRV_EXTENDED_MAJOR_VERSION will be incremented when - driver incompatible changes are made to the Erlang runtime - system. Normally it will suffice to recompile drivers when the - ERL_DRV_EXTENDED_MAJOR_VERSION has changed, but it - could, under rare circumstances, mean that drivers have to - be slightly modified. If so, this will of course be documented. - ERL_DRV_EXTENDED_MINOR_VERSION will be incremented when - new features are added. The runtime system uses the minor version - of the driver to determine what features to use. - The runtime system will normally refuse to load a driver if the major + + extended_marker field of their + driver_entry + to ERL_DRV_EXTENDED_MARKER. erl_driver.h defines:

+ + +

ERL_DRV_EXTENDED_MARKER

+ + +

ERL_DRV_EXTENDED_MAJOR_VERSION, which is incremented when + driver incompatible changes are made to the Erlang runtime + system. Normally it suffices to recompile drivers when + ERL_DRV_EXTENDED_MAJOR_VERSION has changed, but it + can, under rare circumstances, mean that drivers must + be slightly modified. If so, this will of course be + documented.

+ + +

ERL_DRV_EXTENDED_MINOR_VERSION, which is incremented when + new features are added. The runtime system uses the minor version + of the driver to determine what features to use.

+ + +

The runtime system normally refuses to load a driver if the major versions differ, or if the major versions are equal and the minor version used by the driver is greater than the one used by the runtime system. Old drivers with lower major versions - will however be allowed after a bump of the major version during - a transition period of two major releases. Such old drivers might - however fail if deprecated features are used.

-

The emulator will refuse to load a driver that does not use - the extended driver interface, - to allow for 64-bit capable drivers, - since incompatible type changes for the callbacks - output, - control and - call - were introduced in release R15B. A driver written - with the old types would compile with warnings and when - called return garbage sizes to the emulator causing it - to read random memory and create huge incorrect result blobs.

-

Therefore it is not enough to just recompile drivers written with - version management for pre-R15B types; the types have to be changed - in the driver suggesting other rewrites especially regarding - size variables. Investigate all warnings when recompiling!

-

Also, the API driver functions driver_output*, - driver_vec_to_buf, driver_alloc/realloc* - and the driver_* queue functions were changed to have - larger length arguments and return values. This is a - lesser problem since code that passes smaller types - will get them auto converted in the calls and as long as - the driver does not handle sizes that overflow an int - all will work as before.

+ are however allowed after a bump of the major version during + a transition period of two major releases. Such old drivers can, + however, fail if deprecated features are used.

+

The emulator refuses to load a driver that does not use + the extended driver interface, to allow for 64-bit capable drivers, + as incompatible type changes for the callbacks + output, + control, and + call + were introduced in Erlang/OTP R15B. A driver written + with the old types would compile with warnings and when + called return garbage sizes to the emulator, causing it + to read random memory and create huge incorrect result blobs.

+

Therefore it is not enough to only recompile drivers written with + version management for pre R15B types; the types must be changed + in the driver suggesting other rewrites, especially regarding size + variables. Investigate all warnings when recompiling.

+

Also, the API driver functions driver_output* and + driver_vec_to_buf, driver_alloc/realloc*, and the + driver_* queue functions were changed to have + larger length arguments and return values. This is a + lesser problem, as code that passes smaller types + gets them auto-converted in the calls, and as long as + the driver does not handle sizes that overflow an int, + all will work as before.

 - Time Measurement -

Support for time measurement in drivers:

- - ErlDrvTime - ErlDrvTimeUnit - erl_drv_monotonic_time() - erl_drv_time_offset() - erl_drv_convert_time_unit() - + Time measurement + +

Support for time measurement in drivers:

+ + + ErlDrvTime + + ErlDrvTimeUnit + + erl_drv_monotonic_time + + erl_drv_time_offset + + erl_drv_convert_time_unit +
- - REWRITES FOR 64-BIT DRIVER INTERFACE - -

- For erts-5.9 two new integer types - ErlDrvSizeT and - ErlDrvSSizeT - were introduced that can hold 64-bit sizes if necessary. -

-

- To not update a driver and just recompile it probably works + Rewrites for 64-Bit Driver Interface +

ERTS 5.9 introduced two new integer types, + ErlDrvSizeT and + ErlDrvSSizeT, + which can hold 64-bit sizes if necessary.

+ +

To not update a driver and only recompile, it probably works when building for a 32-bit machine creating a false sense of security. Hopefully that will generate many important warnings. - But when recompiling the same driver later on for a 64-bit machine + But when recompiling the same driver later on for a 64-bit machine, there will be warnings and almost certainly crashes. - So it is a BAD idea to postpone updating the driver and - not fixing the warnings! -

-

- When recompiling with gcc use the -Wstrict-prototypes - flag to get better warnings. Try to find a similar flag if you - are using some other compiler. -

-

- Here follows a checklist for rewriting a pre erts-5.9 driver, - most important first. -

+ So it is a bad idea to postpone updating the driver and + not fixing the warnings.

+ +

When recompiling with gcc, use flag -Wstrict-prototypes + to get better warnings. Try to find a similar flag if you use + another compiler.

+ +

The following is a checklist for rewriting a pre ERTS 5.9 driver, + most important first:

+ Return types for driver callbacks -

- Rewrite driver callback +

Rrewrite driver callback control - to use return type ErlDrvSSizeT instead of int. -

-

- Rewrite driver callback + to use return type ErlDrvSSizeT instead of int.

+

Rewrite driver callback call - to use return type ErlDrvSSizeT instead of int. -

+ to use return type ErlDrvSSizeT instead of int.

-

- These changes are essential to not crash the emulator +

These changes are essential not to crash the emulator or worse cause malfunction. - Without them a driver may return garbage in the high 32 bits - to the emulator causing it to build a huge result from random - bytes either crashing on memory allocation or succeeding with - a random result from the driver call. -

+ Without them a driver can return garbage in the high 32 bits + to the emulator, causing it to build a huge result from random + bytes, either crashing on memory allocation or succeeding with + a random result from the driver call.

 Arguments to driver callbacks -

- Driver callback +

Driver callback output now gets ErlDrvSizeT as 3rd argument instead - of previously int. -

-

- Driver callback + of previously int.

+

Driver callback control now gets ErlDrvSizeT as 4th and 6th arguments instead - of previously int. -

-

- Driver callback + of previously int.

+

Driver callback call now gets ErlDrvSizeT as 4th and 6th arguments instead - of previously int. -

-

- Sane compiler's calling conventions probably make these changes + of previously int.

+

Sane compiler's calling conventions probably make these changes necessary only for a driver to handle data chunks that require - 64-bit size fields (mostly larger than 2 GB since that is what + 64-bit size fields (mostly larger than 2 GB, as that is what an int of 32 bits can hold). But it is possible to think of non-sane calling conventions that would make the driver - callbacks mix up the arguments causing malfunction. -

+ callbacks mix up the arguments causing malfunction.

-

- The argument type change is from signed to unsigned which - may cause problems for e.g. loop termination conditions or - error conditions if you just change the types all over the place. -

+

The argument type change is from signed to unsigned. This + can cause problems for, for example, loop termination conditions or + error conditions if you only change the types all over the place. +

Larger size field in ErlIOVec -

- The size field in +

The size field in ErlIOVec has been changed to ErlDrvSizeT from int. - Check all code that use that field. -

-

- Automatic type casting probably makes these changes necessary only - for a driver that encounters sizes larger than 32 bits. -

+ Check all code that use that field.

+

Automatic type-casting probably makes these changes necessary only + for a driver that encounters sizes > 32 bits.

-

- The size field changed from signed to unsigned which - may cause problems for e.g. loop termination conditions or - error conditions if you just change the types all over the place. -

+

The size field changed from signed to unsigned. This + can cause problems for, for example, loop termination conditions or + error conditions if you only change the types all over the place. +

Arguments and return values in the driver API -

- Many driver API functions have changed argument type +

Many driver API functions have changed argument type and/or return value to ErlDrvSizeT from mostly int. - Automatic type casting probably makes these changes necessary only - for a driver that encounters sizes larger than 32 bits. -

+ Automatic type-casting probably makes these changes necessary only + for a driver that encounters sizes > 32 bits.

- driver_output + + driver_output 3rd argument - driver_output2 + + driver_output2 3rd and 5th arguments - - driver_output_binary - - 3rd 5th and 6th arguments - driver_outputv + + driver_output_binary + 3rd, 5th, and 6th arguments + + driver_outputv 3rd and 5th arguments - - driver_vec_to_buf - + + driver_vec_to_buf 3rd argument and return value - driver_alloc + + driver_alloc 1st argument - driver_realloc + + driver_realloc 2nd argument - - driver_alloc_binary - + + driver_alloc_binary 1st argument - - driver_realloc_binary - + + driver_realloc_binary 2nd argument - driver_enq + + driver_enq 3rd argument - driver_pushq + + driver_pushq 3rd argument - driver_deq + + driver_deq 2nd argument and return value - driver_sizeq - return value - driver_enq_bin - 3rd and 4th argument - driver_pushq_bin - 3rd and 4th argument - driver_enqv + + driver_sizeq + Return value + + driver_enq_bin + 3rd and 4th arguments + + driver_pushq_bin + 3rd and 4th arguments + + driver_enqv 3rd argument - driver_pushqv + + driver_pushqv 3rd argument - driver_peekqv - return value + + driver_peekqv + Return value -

- This is a change from signed to unsigned which - may cause problems for e.g. loop termination conditions and - error conditions if you just change the types all over the place. -

+

This is a change from signed to unsigned. This can cause + problems for, for example, loop termination conditions and error + conditions if you only change the types all over the place.
- DATA TYPES - + Data Types - ErlDrvSizeT -

An unsigned integer type to be used as size_t

 - ErlDrvSSizeT -

A signed integer type the size of ErlDrvSizeT

 - ErlDrvSysInfo + ErlDrvSizeT + +

An unsigned integer type to be used as size_t.

+ + ErlDrvSSizeT -

- +

A signed integer type, the size of ErlDrvSizeT.

+ + ErlDrvSysInfo + + typedef struct ErlDrvSysInfo { int driver_major_version; int driver_minor_version; @@ -558,390 +584,422 @@ typedef struct ErlDrvSysInfo { int nif_major_version; int nif_minor_version; int dirty_scheduler_support; -} ErlDrvSysInfo; - - -

- The ErlDrvSysInfo structure is used for storage of - information about the Erlang runtime system. - driver_system_info() - will write the system information when passed a reference to - a ErlDrvSysInfo structure. A description of the - fields in the structure follows: -

- - driver_major_version - The value of - ERL_DRV_EXTENDED_MAJOR_VERSION - when the runtime system was compiled. This value is the same - as the value of - ERL_DRV_EXTENDED_MAJOR_VERSION - used when compiling the driver; otherwise, the runtime system - would have refused to load the driver. - - driver_minor_version - The value of - ERL_DRV_EXTENDED_MINOR_VERSION - when the runtime system was compiled. This value might differ - from the value of - ERL_DRV_EXTENDED_MINOR_VERSION - used when compiling the driver. - - erts_version - A string containing the version number of the runtime system - (the same as returned by - erlang:system_info(version)). - - otp_release - A string containing the OTP release number - (the same as returned by - erlang:system_info(otp_release)). - - thread_support - A value != 0 if the runtime system has thread support; - otherwise, 0. - - smp_support - A value != 0 if the runtime system has SMP support; - otherwise, 0. - - async_threads - The number of async threads in the async thread pool used - by driver_async() - (the same as returned by - erlang:system_info(thread_pool_size)). - - scheduler_threads - The number of scheduler threads used by the runtime system - (the same as returned by - erlang:system_info(schedulers)). - - nif_major_version - The value of ERL_NIF_MAJOR_VERSION when the runtime system was compiled. - - nif_minor_version - The value of ERL_NIF_MINOR_VERSION when the runtime system was compiled. - - dirty_scheduler_support - A value != 0 if the runtime system has support for dirty scheduler threads; - otherwise 0. - +} ErlDrvSysInfo; +

The ErlDrvSysInfo structure is used for storage of + information about the Erlang runtime system. + + driver_system_info + writes the system information when passed a reference to + a ErlDrvSysInfo structure. The fields in the structure + are as follows:

+ + driver_major_version + +

The value of + ERL_DRV_EXTENDED_MAJOR_VERSION + when the runtime system was compiled. This value is the same + as the value of + ERL_DRV_EXTENDED_MAJOR_VERSION + used when compiling the driver; otherwise the runtime system + would have refused to load the driver.

+ + driver_minor_version + +

The value of + ERL_DRV_EXTENDED_MINOR_VERSION + when the runtime system was compiled. This value can differ + from the value of + ERL_DRV_EXTENDED_MINOR_VERSION + used when compiling the driver.

+ + erts_version + +

A string containing the version number of the runtime system + (the same as returned by + + erlang:system_info(version)).

+ + otp_release + +

A string containing the OTP release number + (the same as returned by + + erlang:system_info(otp_release)).

+ + thread_support + +

A value != 0 if the runtime system has thread support; + otherwise 0.

+ + smp_support + +

A value != 0 if the runtime system has SMP support; + otherwise 0.

+ + async_threads + +

The number of async threads in the async thread pool used by + driver_async + (the same as returned by + + erlang:system_info(thread_pool_size)).

+ + scheduler_threads + +

The number of scheduler threads used by the runtime system + (the same as returned by + + erlang:system_info(schedulers)).

+ + nif_major_version + +

The value of ERL_NIF_MAJOR_VERSION when the runtime + system was compiled.

+ + nif_minor_version + +

The value of ERL_NIF_MINOR_VERSION when the runtime + system was compiled.

+ + dirty_scheduler_support + +

A value != 0 if the runtime system has support for dirty + scheduler threads; otherwise 0.

+ - ErlDrvBinary + ErlDrvBinary -

- + typedef struct ErlDrvBinary { ErlDrvSint orig_size; char orig_bytes[]; -} ErlDrvBinary; - +} ErlDrvBinary;

The ErlDrvBinary structure is a binary, as sent between the emulator and the driver. All binaries are reference counted; when driver_binary_free is called, the reference count is decremented, when it reaches zero, - the binary is deallocated. The orig_size is the size - of the binary, and orig_bytes is the buffer. The - ErlDrvBinary does not have a fixed size, its size is + the binary is deallocated. orig_size is the binary size + and orig_bytes is the buffer. + ErlDrvBinary has not a fixed size, its size is orig_size + 2 * sizeof(int).

The refc field has been removed. The reference count of an ErlDrvBinary is now stored elsewhere. The - reference count of an ErlDrvBinary can be accessed via - driver_binary_get_refc(), - driver_binary_inc_refc(), - and - driver_binary_dec_refc().

+ reference count of an ErlDrvBinary can be accessed through + + driver_binary_get_refc, + + driver_binary_inc_refc, and + + driver_binary_dec_refc.

Some driver calls, such as driver_enq_binary, increment the driver reference count, and others, such as driver_deq decrement it.

-

Using a driver binary instead of a normal buffer, is often - faster, since the emulator doesn't need to copy the data, +

Using a driver binary instead of a normal buffer is often + faster, as the emulator needs not to copy the data, only the pointer is used.

A driver binary allocated in the driver, with - driver_alloc_binary, should be freed in the driver (unless otherwise stated), - with driver_free_binary. (Note that this doesn't + driver_alloc_binary, is to be freed in the driver + (unless otherwise stated) + with driver_free_binary. (Notice that this does not necessarily deallocate it, if the driver is still referred in the emulator, the ref-count will not go to zero.)

Driver binaries are used in the driver_output2 and driver_outputv calls, and in the queue. Also the - driver call-back outputv uses driver - binaries.

-

If the driver for some reason or another, wants to keep a - driver binary around, in a static variable for instance, the - reference count should be incremented, - and the binary can later be freed in the stop call-back, with - driver_free_binary.

-

Note that since a driver binary is shared by the driver and - the emulator, a binary received from the emulator or sent to - the emulator, must not be changed by the driver.

-

Since erts version 5.5 (OTP release R11B), orig_bytes is + driver callback + outputv uses driver binaries.

+

If the driver for some reason wants to keep a + driver binary around, for example in a static variable, the + reference count is to be incremented, and the binary can later + be freed in the + stop callback, with driver_free_binary.

+

Notice that as a driver binary is shared by the driver and + the emulator. A binary received from the emulator or sent to + the emulator must not be changed by the driver.

+

Since ERTS 5.5 (Erlang/OTP R11B), orig_bytes is guaranteed to be properly aligned for storage of an array of doubles (usually 8-byte aligned).

 - ErlDrvData + ErlDrvData -

The ErlDrvData is a handle to driver-specific data, - passed to the driver call-backs. It is a pointer, and is +

A handle to driver-specific data, + passed to the driver callbacks. It is a pointer, and is most often type cast to a specific pointer in the driver.

 - SysIOVec + SysIOVec -

This is a system I/O vector, as used by writev on - unix and WSASend on Win32. It is used in +

A system I/O vector, as used by writev on + Unix and WSASend on Win32. It is used in ErlIOVec.

 - ErlIOVec + ErlIOVec -

- + typedef struct ErlIOVec { int vsize; ErlDrvSizeT size; SysIOVec* iov; ErlDrvBinary** binv; -} ErlIOVec; - -

The I/O vector used by the emulator and drivers, is a list +} ErlIOVec; +

The I/O vector used by the emulator and drivers is a list of binaries, with a SysIOVec pointing to the buffers of the binaries. It is used in driver_outputv and the - outputv - driver call-back. Also, the driver queue is an + outputv + driver callback. Also, the driver queue is an ErlIOVec.

 - - ErlDrvMonitor + ErlDrvMonitor

When a driver creates a monitor for a process, a ErlDrvMonitor is filled in. This is an opaque - data-type which can be assigned to but not compared without - using the supplied compare function (i.e. it behaves like a struct).

-

The driver writer should provide the memory for storing the - monitor when calling driver_monitor_process. The + data type that can be assigned to, but not compared without + using the supplied compare function (that is, it behaves like + a struct).

+

The driver writer is to provide the memory for storing the + monitor when calling + driver_monitor_process. The address of the data is not stored outside of the driver, so - the ErlDrvMonitor can be used as any other datum, it - can be copied, moved in memory, forgotten etc.

+ ErlDrvMonitor can be used as any other data, it + can be copied, moved in memory, forgotten, and so on.

 - ErlDrvNowData + ErlDrvNowData -

The ErlDrvNowData structure holds a timestamp +

The ErlDrvNowData structure holds a time stamp consisting of three values measured from some arbitrary point in the past. The three structure members are:

- megasecs + megasecs The number of whole megaseconds elapsed since the arbitrary - point in time - secs + point in time + secs The number of whole seconds elapsed since the arbitrary - point in time - microsecs + point in time + microsecs The number of whole microseconds elapsed since the arbitrary - point in time + point in time - ErlDrvPDL + ErlDrvPDL -

If certain port specific data have to be accessed from other - threads than those calling the driver call-backs, a port data lock - can be used in order to synchronize the operations on the data. - Currently, the only port specific data that the emulator +

If certain port-specific data must be accessed from other + threads than those calling the driver callbacks, a port data lock + can be used to synchronize the operations on the data. + Currently, the only port-specific data that the emulator associates with the port data lock is the driver queue.

-

Normally a driver instance does not have a port data lock. If - the driver instance wants to use a port data lock, it has to +

Normally a driver instance has no port data lock. If + the driver instance wants to use a port data lock, it must create the port data lock by calling - driver_pdl_create(). - NOTE: Once the port data lock has been created, every - access to data associated with the port data lock has to be done - while having the port data lock locked. The port data lock is - locked, and unlocked, respectively, by use of - driver_pdl_lock(), and - driver_pdl_unlock().

+ + driver_pdl_create.

+ +

Once the port data lock has been created, every + access to data associated with the port data lock must be done + while the port data lock is locked. The port data lock is + locked and unlocked by + + driver_pdl_lock, and + + driver_pdl_unlock, respectively.

+

A port data lock is reference counted, and when the reference - count reaches zero, it will be destroyed. The emulator will at - least increment the reference count once when the lock is - created and decrement it once when the port associated with - the lock terminates. The emulator will also increment the - reference count when an async job is enqueued and decrement - it after an async job has been invoked. Besides - this, it is the responsibility of the driver to ensure that + count reaches zero, it is destroyed. The emulator at + least increments the reference count once when the lock is + created and decrements it once the port associated with + the lock terminates. The emulator also increments the + reference count when an async job is enqueued and decrements + it when an async job has been invoked. + Also, the driver is responsible for ensuring that the reference count does not reach zero before the last use of the lock by the driver has been made. The reference count - can be read, incremented, and decremented, respectively, by - use of - driver_pdl_get_refc(), - driver_pdl_inc_refc(), and - driver_pdl_dec_refc().

+ can be read, incremented, and decremented by + + driver_pdl_get_refc, + + driver_pdl_inc_refc, and + + driver_pdl_dec_refc, respectively.

 - - ErlDrvTid + ErlDrvTid

Thread identifier.

-

See also: - erl_drv_thread_create(), - erl_drv_thread_exit(), - erl_drv_thread_join(), - erl_drv_thread_self(), - and - erl_drv_equal_tids(). -

+

See also + erl_drv_thread_create, + + erl_drv_thread_exit, + + erl_drv_thread_join, + + erl_drv_thread_self, and + + erl_drv_equal_tids.

 - ErlDrvThreadOpts + ErlDrvThreadOpts -

- - int suggested_stack_size; - + +int suggested_stack_size;

Thread options structure passed to - erl_drv_thread_create(). - Currently the following fields exist: -

+ + erl_drv_thread_create. + The following fields exists:

- suggested_stack_size - A suggestion, in kilo-words, on how large a stack to use. A value less - than zero means default size. + suggested_stack_size + A suggestion, in kilowords, on how large a stack to use. + A value < 0 means default size. -

See also: - erl_drv_thread_opts_create(), - erl_drv_thread_opts_destroy(), - and - erl_drv_thread_create(). -

+

See also + erl_drv_thread_opts_create, + + erl_drv_thread_opts_destroy, and + + erl_drv_thread_create.

 - - ErlDrvMutex + ErlDrvMutex

Mutual exclusion lock. Used for synchronizing access to shared data. - Only one thread at a time can lock a mutex. -

-

See also: - erl_drv_mutex_create(), - erl_drv_mutex_destroy(), - erl_drv_mutex_lock(), - erl_drv_mutex_trylock(), - and - erl_drv_mutex_unlock(). -

+ Only one thread at a time can lock a mutex.

+

See also + erl_drv_mutex_create, + + erl_drv_mutex_destroy, + + erl_drv_mutex_lock, + + erl_drv_mutex_trylock, and + + erl_drv_mutex_unlock.

 - ErlDrvCond + ErlDrvCond -

Condition variable. Used when threads need to wait for a specific - condition to appear before continuing execution. Condition variables - need to be used with associated mutexes. -

-

See also: - erl_drv_cond_create(), - erl_drv_cond_destroy(), - erl_drv_cond_signal(), - erl_drv_cond_broadcast(), - and - erl_drv_cond_wait(). -

+

Condition variable. Used when threads must wait for a specific + condition to appear before continuing execution. Condition variables + must be used with associated mutexes.

+

See also + erl_drv_cond_create, + + erl_drv_cond_destroy, + + erl_drv_cond_signal, + + erl_drv_cond_broadcast, and + + erl_drv_cond_wait.

 - ErlDrvRWLock + ErlDrvRWLock

Read/write lock. Used to allow multiple threads to read shared data - while only allowing one thread to write the same data. Multiple threads - can read lock an rwlock at the same time, while only one thread can - read/write lock an rwlock at a time. -

-

See also: - erl_drv_rwlock_create(), - erl_drv_rwlock_destroy(), - erl_drv_rwlock_rlock(), - erl_drv_rwlock_tryrlock(), - erl_drv_rwlock_runlock(), - erl_drv_rwlock_rwlock(), - erl_drv_rwlock_tryrwlock(), - and - erl_drv_rwlock_rwunlock(). -

+ while only allowing one thread to write the same data. Multiple + threads can read lock an rwlock at the same time, while only + one thread can read/write lock an rwlock at a time.

+

See also + erl_drv_rwlock_create, + + erl_drv_rwlock_destroy, + + erl_drv_rwlock_rlock, + + erl_drv_rwlock_tryrlock, + + erl_drv_rwlock_runlock, + + erl_drv_rwlock_rwlock, + + erl_drv_rwlock_tryrwlock, and + + erl_drv_rwlock_rwunlock.

 - ErlDrvTSDKey + ErlDrvTSDKey -

Key which thread specific data can be associated with.

-

See also: - erl_drv_tsd_key_create(), - erl_drv_tsd_key_destroy(), - erl_drv_tsd_set(), - and - erl_drv_tsd_get(). -

+

Key that thread-specific data can be associated with.

+

See also + erl_drv_tsd_key_create, + + erl_drv_tsd_key_destroy, + + erl_drv_tsd_set, and + + erl_drv_tsd_get.

 - ErlDrvTime + ErlDrvTime -

A signed 64-bit integer type for representation of time.

+

A signed 64-bit integer type for time representation.

 - ErlDrvTimeUnit + ErlDrvTimeUnit

An enumeration of time units supported by the driver API:

- + ERL_DRV_SEC -

Seconds

 + Seconds ERL_DRV_MSEC -

Milliseconds

 + Milliseconds ERL_DRV_USEC -

Microseconds

 + Microseconds ERL_DRV_NSEC -

Nanoseconds

 - + Nanoseconds + - -
+ +
- voidadd_driver_entry(ErlDrvEntry *de) - Add a driver entry + voidadd_driver_entry(ErlDrvEntry + *de) + Add a driver entry. -

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

+

Adds a driver entry to the list of drivers known by Erlang. + The init + function of parameter de 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 + loaded module (that is, .so file) as a normal dynamically loaded driver (loaded with the erl_ddll - interface), the caller should call driver_lock_driver before + interface), the caller is to call + + driver_lock_driver before adding driver entries.

-

Use of this function is generally deprecated.

+

Use of this function is generally deprecated.

 - void *driver_alloc(ErlDrvSizeT size) - Allocate memory + void * + driver_alloc(ErlDrvSizeT size) + Allocate memory. -

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 +

Allocates a memory block of the size specified + in size, and returns it. This fails only on out of + memory, in which 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).

+ call to driver_free (unless otherwise stated).

This function is thread-safe.

 - ErlDrvBinary *driver_alloc_binary(ErlDrvSizeT size) - Allocate a driver binary + ErlDrvBinary * + driver_alloc_binary(ErlDrvSizeT size) + Allocate a driver binary. -

This function allocates a driver binary with a memory block +

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 + or NULL on failure (out of memory). When a driver binary has + been sent to the emulator, it must not be changed. Every + allocated binary is to be freed by a corresponding call to + + driver_free_binary (unless otherwise stated).

+

Notice 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 is sent to the emulator, it can be referenced there.

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

@@ -950,94 +1008,97 @@ typedef struct ErlIOVec { - 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 + 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 +

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 +

The async thread pool size can be set with command-line argument + +A + in erl(1). + If an async thread pool is unavailable, 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 + retrieved through + driver_system_info.

+

If a thread pool is available, a thread is used. + If argument key 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 + driver_async uses the next thread in the pool. With + argument key set, this behavior is changed. The two same values of *key always get the same thread.

-

To make sure that a driver instance always uses the same +

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

-

+r = driver_async(myPort, &myKey, myData, myFunc); ]]>

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

-

If a thread is already working, the calls will be + driver instance.

+

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

+ each driver instance ensures that the calls are 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 + async_invoke and async_free. It is typically a + pointer to a structure containing 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 data is to 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 +

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

-

As of erts version 5.5.4.3 the default stack size for +

As from ERTS 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 + that is, 64 kilobyte on 32-bit architectures. + This small default size has been chosen because the + amount of async-threads can 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 + with Erlang/OTP, but is possibly not 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).

+ through command-line argument + +a + in erl(1).

 - - unsigned intdriver_async_port_key (ErlDrvPort port) - Calculate an async key from an ErlDrvPort + + + unsigned intdriver_async_port_key (ErlDrvPort + port) + Calculate an async key from an ErlDrvPort. -

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.

- +

Calculates a key for later use in driver_async. The keys are + evenly distributed so that a fair mapping between port IDs + and async thread IDs is achieved.

+ +

Before Erlang/OTP R16, the 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 IDs as before + Erlang/OTP R16.

+ - longdriver_binary_dec_refc(ErlDrvBinary *bin) - Decrement the reference count of a driver binary + long + driver_binary_dec_refc(ErlDrvBinary *bin) + Decrement the reference count of a driver binary.

Decrements the reference count on bin and returns @@ -1045,31 +1106,33 @@ typedef struct ErlIOVec {

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 reference count of driver binary is normally to be decremented + 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 + use driver_binary_dec_refc when you are sure not to reach a reference count of zero.

 - longdriver_binary_get_refc(ErlDrvBinary *bin) - Get the reference count of a driver binary + long + driver_binary_get_refc(ErlDrvBinary *bin) + Get the reference count of a driver binary. -

Returns current reference count on bin.

+

Returns the 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 + long + driver_binary_inc_refc(ErlDrvBinary *bin) + Increment the reference count of a driver binary.

Increments the reference count on bin and returns @@ -1080,143 +1143,158 @@ typedef struct ErlIOVec { - ErlDrvTermDatadriver_caller(ErlDrvPort port) - Return the process making the driver call + ErlDrvTermDatadriver_caller(ErlDrvPort + port) + Return the process making the driver call. -

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 +

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 + erlang: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. + +

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

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

This function cancels a timer set with - driver_set_timer.

-

The return value is 0.

+

Cancels a timer set with + + driver_set_timer.

+

The return value is 0.

 - intdriver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2) - Compare two monitors + intdriver_compare_monitors(const ErlDrvMonitor + *monitor1, const ErlDrvMonitor *monitor2) + Compare two monitors. -

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

Compares two ErlDrvMonitors. + 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.

+

Returns 0 if monitor1 and monitor2 are equal, + < 0 if monitor1 < monitor2, and + > 0 if monitor1 > monitor2.

 - ErlDrvTermDatadriver_connected(ErlDrvPort port) - Return the port owner process + ErlDrvTermDatadriver_connected(ErlDrvPort + port) + Return the port owner process. -

This function returns the port owner process.

-

Note that this function is not thread-safe, not +

Returns the port owner process.

+

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

 - ErlDrvPortdriver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data) - Create a new port (driver instance) + ErlDrvPortdriver_create_port(ErlDrvPort port, + ErlDrvTermData owner_pid, char* name, + ErlDrvData drv_data) + Create a new port (driver instance). -

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

+

Creates a new port executing the same driver + code as the port creating the new port.

port The port handle of the port (driver instance) creating - the new port. + 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. + The process ID of the Erlang process to become + 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). + 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 driver-defined handle that is passed in later + calls to driver callbacks. Notice that the + driver start + callback is not called for this new driver instance. + The driver-defined handle is normally created in the + driver start callback + when a port is created through + + erlang:open_port/2. + -

The caller of driver_create_port() is allowed to - manipulate the newly created port when driver_create_port() +

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 + is used, the creating port is 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.

- + callback, which was called by the emulator, returns.

 - intdriver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor) - Stop monitoring a process from a driver + intdriver_demonitor_process(ErlDrvPort port, + const ErlDrvMonitor *monitor) + Stop monitoring a process from a driver. -

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.

+

Cancels a monitor created earlier.

+

Returns 0 if a monitor was removed and > 0 if the monitor + no longer exists.

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

This function dequeues data by moving the head pointer +

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 + in the queue is deallocated.

+

Returns the number of bytes remaining in the queue on success, + otherwise -1.

+

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

@@ -1224,24 +1302,25 @@ typedef struct ErlIOVec { - 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 +

Enqueues data in the driver queue. The data in buf is copied (len bytes) and placed at the end of the driver queue. The driver queue is normally used in a FIFO way.

The driver queue is available to queue output from the emulator to the driver (data from the driver to the emulator - is queued by the emulator in normal erlang message - queues). This can be useful if the driver has to wait for - slow devices etc, and wants to yield back to the - emulator. The driver queue is implemented as an ErlIOVec.

-

When the queue contains data, the driver won't close, until + is queued by the emulator in normal Erlang message + queues). This can be useful if the driver must wait for + slow devices, and so on, and wants to yield back to the + emulator. The driver queue is implemented as an ErlIOVec.

+

When the queue contains data, the driver does not close until the queue is empty.

-

The return value is 0.

-

This function can be called from an arbitrary thread if a +

The return value is 0.

+

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

@@ -1249,34 +1328,39 @@ typedef struct ErlIOVec { - intdriver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) - Enqueue binary in the driver queue + intdriver_enq_bin(ErlDrvPort port, + ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) + + Enqueue binary in the driver queue. -

This function enqueues a driver binary in the driver +

Enqueues a driver binary in the driver queue. The data in bin at offset with length len is placed at the end of the queue. This function - is most often faster than driver_enq, because the - data doesn't have to be copied.

-

This function can be called from an arbitrary thread if a + is most often faster than + driver_enq, + because no data must be copied.

+

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

-

The return value is 0.

+

The return value is 0.

 - intdriver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip) - Enqueue vector in the driver queue + intdriver_enqv(ErlDrvPort port, ErlIOVec *ev, + ErlDrvSizeT skip) + Enqueue vector in the driver queue. -

This function enqueues the data in ev, skipping the +

Enqueues the data in ev, skipping the first skip bytes of it, at the end of the driver - queue. It is faster than driver_enq, 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 + queue. It is faster than + driver_enq, + because no data must be copied.

+

The return value is 0.

+

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

@@ -1284,283 +1368,320 @@ typedef struct ErlIOVec { - intdriver_failure_atom(ErlDrvPort port, char *string) - intdriver_failure_posix(ErlDrvPort port, int error) - intdriver_failure(ErlDrvPort port, int error) - Fail with error + intdriver_failure(ErlDrvPort port, int + error) + intdriver_failure_atom(ErlDrvPort port, char + *string) + intdriver_failure_posix(ErlDrvPort port, int + error) + Fail with error. -

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 +

Signals to Erlang that the driver has + encountered an error and is to 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_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 +

The driver is to fail only when in severe error situations, + when the driver cannot possibly keep open, for example, 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.

+ driver_output.

+

The return value is 0.

 - intdriver_failure_eof(ErlDrvPort port) - Fail with EOF + intdriver_failure_eof(ErlDrvPort + port) + Fail with EOF. -

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 +

Signals to Erlang that the driver has + encountered an EOF and is to be closed, unless the port was + opened with option eof, in which 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.

+

The return value is 0.

 voiddriver_free(void *ptr) - Free an allocated memory block + Free an allocated memory block. -

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 +

Frees the memory pointed to by ptr. The + memory is to have been allocated with + driver_alloc. All allocated memory is to be + deallocated, only once. There is no garbage collection in drivers.

This function is thread-safe.

 - voiddriver_free_binary(ErlDrvBinary *bin) - Free a driver binary + void + driver_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.

+

Frees a driver binary bin, allocated previously with + + driver_alloc_binary. As binaries + in Erlang are reference counted, the binary can still be around.

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

 - ErlDrvTermDatadriver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor) - Retrieve the process id from a monitor + ErlDrvTermData + driver_get_monitored_process(ErlDrvPort port, const + ErlDrvMonitor *monitor) + Retrieve the process ID from a monitor. -

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.

+

Returns the process ID associated with a living + monitor. It can be used in the + + process_exit callback to + get the process identification for the exiting process.

+

Returns driver_term_nil if the monitor no longer exists.

 - intdriver_get_now(ErlDrvNowData *now) - Read a system timestamp + int + driver_get_now(ErlDrvNowData *now) + Read a system time stamp. -

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 is deprecated. Do not use it. Use + + erl_drv_monotonic_time (perhaps in combination with + + erl_drv_time_offset) instead.

+ +

Reads a time stamp into the memory pointed to by + parameter now. For information about specific fields, see + ErlDrvNowData.

+

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

 - intdriver_lock_driver(ErlDrvPort port) - Make sure the driver is never unloaded + intdriver_lock_driver(ErlDrvPort + port) + Ensure the driver is never unloaded. -

This function locks the driver used by the port port +

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.

+ statically linked-in drivers.

 - ErlDrvTermDatadriver_mk_atom(char* string) - Make an atom from a name + 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 +

Returns an atom given a name + string. The atom is created and does not change, so the + return value can be saved and reused, which is faster than looking up the atom several times.

-

Note that this function is not thread-safe, not +

Notice 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 + ErlDrvTermDatadriver_mk_port(ErlDrvPort + port) + Make an 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 +

Converts a port handle to the Erlang term format, usable in + + erl_drv_output_term and + + erl_drv_send_term.

+

Notice 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 + intdriver_monitor_process(ErlDrvPort port, + ErlDrvTermData process, ErlDrvMonitor *monitor) + Monitor a process from a driver. -

Start monitoring a process from a driver. When a process is - monitored, a process exit will result in a call to the - provided process_exit call-back - in the ErlDrvEntry +

Starts monitoring a process from a driver. When a process is + monitored, a process exit results in a call to the provided + + process_exit callback + in the ErlDrvEntry structure. The ErlDrvMonitor structure is filled in, for later removal or compare.

-

The process parameter should be the return value of an - earlier call to driver_caller or driver_connected call.

-

The function returns 0 on success, < 0 if no call-back is - provided and > 0 if the process is no longer alive.

+

Parameter process is to be the return value of an + earlier call to + driver_caller or + driver_connected + call.

+

Returns 0 on success, < 0 if no callback is + provided, and > 0 if the process is no longer alive.

 - intdriver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len) - Send data from driver to port owner + intdriver_output(ErlDrvPort port, char *buf, + ErlDrvSizeT len) + Send data from driver to port owner. -

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 +

Sends data from the driver up to the emulator. The data is 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 + queue. Notice that this does not yield to the emulator (as + the driver and the emulator run in the same thread).

+

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.)

+

The return value for all output functions is 0 for normal use. + If the driver is used for distribution, it can fail and return + -1.

 - intdriver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len) - Send data from a driver binary to port owner + intdriver_output_binary(ErlDrvPort port, char + *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, + ErlDrvSizeT len) + Send data from a driver binary to port owner. -

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 +

Sends data to a port owner process from a + driver binary. It has a header buffer (hbuf + and hlen) just like + driver_output2. + Parameter hbuf can be NULL.

+

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.

+

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 +

For example, if hlen is 2, the port owner process + receives >]]]>.

+

The return value is 0 for normal use.

+

Notice 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.

+ so the header can be put in the binary, and hlen can be set + to 0.

 - intdriver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n) - Send term data from driver to port owner + intdriver_output_term(ErlDrvPort port, + ErlDrvTermData* term, int n) + Send term data from driver to port owner. -

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 + +

This function is deprecated. + Use + erl_drv_output_terminstead.

+ +

Parameters term and n work as in + + erl_drv_output_term.

+

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

 - intdriver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len) - Send data and binary data to port owner + intdriver_output2(ErlDrvPort port, char *hbuf, + ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len) + Send data and binary data to port owner. -

The driver_output2 function first sends hbuf +

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].

+ settings. Then sends buf as a binary or list. + For example, if hlen is 3, the port owner process + receives [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.

+

The return value is 0 for normal use.

 - intdriver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip) - Send vectorized data to port owner + intdriver_outputv(ErlDrvPort port, char* hbuf, + ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip) + Send vectorized data to port owner. -

This function sends data from an IO vector, ev, to +

Sends data from an I/O 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 + and hlen), just like + driver_output2.

+

Parameter skip 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 + 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.

+ it is faster to use + driver_output or + .

+

For example, if hlen is 2 and ev points to an + array of three binaries, the port owner process receives + >, <> | <>]]]>.

+

The return value is 0 for normal use.

+

The comment for driver_output_binary also applies for + driver_outputv.

 - ErlDrvPDLdriver_pdl_create(ErlDrvPort port) - Create a port data lock + ErlDrvPDL + driver_pdl_create(ErlDrvPort port) + Create a port data lock. -

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 +

Creates a port data lock associated with the port.

+ +

Once a port data lock has been created, it must be locked during + all operations on the driver queue of the port.

+ +

Returns a newly created port data lock on success, + otherwise NULL. The function fails + if port is invalid or if a port data lock already has been associated with the port.

 - longdriver_pdl_dec_refc(ErlDrvPDL pdl) + longdriver_pdl_dec_refc(ErlDrvPDL + pdl) -

This function decrements the reference count of +

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.

@@ -1569,22 +1690,24 @@ typedef struct ErlIOVec { - longdriver_pdl_get_refc(ErlDrvPDL pdl) + long + driver_pdl_get_refc(ErlDrvPDL pdl) -

This function returns the current reference count of +

Returns the current reference count of the port data lock passed as argument (pdl).

This function is thread-safe.

 - longdriver_pdl_inc_refc(ErlDrvPDL pdl) + long + driver_pdl_inc_refc(ErlDrvPDL pdl) -

This function increments the reference count of +

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.

@@ -1593,41 +1716,42 @@ typedef struct ErlIOVec { - voiddriver_pdl_lock(ErlDrvPDL pdl) - Lock port data lock + void + driver_pdl_lock(ErlDrvPDL pdl) + Lock port data lock. -

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

+

Locks the port data lock passed as argument (pdl).

This function is thread-safe.

 - voiddriver_pdl_unlock(ErlDrvPDL pdl) - Unlock port data lock + void + driver_pdl_unlock(ErlDrvPDL pdl) + Unlock port data lock. -

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

+

Unlocks the port data lock passed as argument (pdl).

This function is thread-safe.

 - SysIOVec *driver_peekq(ErlDrvPort port, int *vlen) - Get the driver queue as a vector + 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 +

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.

+ 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 +

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

@@ -1635,22 +1759,19 @@ typedef struct ErlIOVec { - ErlDrvSizeTdriver_peekqv(ErlDrvPort port, ErlIOVec *ev) - Get the driver queue as an IO vector + ErlDrvSizeTdriver_peekqv(ErlDrvPort port, + ErlIOVec *ev) + Get the driver queue as an I/O vector. -

- This function retrieves the driver queue into a supplied +

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. -

+ This is one of two ways to get data out of the queue.

+

If ev is NULL, all ones that is -1 type cast to + ErlDrvSizeT are 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 + with driver_deq.

+

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

@@ -1658,15 +1779,16 @@ typedef struct ErlIOVec { - intdriver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len) - Push data at the head of the driver queue + 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 +

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 +

The return value is 0.

+

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

@@ -1674,34 +1796,38 @@ typedef struct ErlIOVec { - intdriver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) - Push binary at the head of the driver queue + 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 +

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 + driver_pushq, + because no data must be copied.

+

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

-

The return value is 0.

+

The return value is 0.

 - intdriver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip) - Push vector at the head of the driver queue + intdriver_pushqv(ErlDrvPort port, ErlIOVec + *ev, ErlDrvSizeT skip) + Push vector at the head of the driver queue. -

This function puts the data in ev, skipping the first +

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 + It is faster than + driver_pushq, + because no data must be copied.

+

The return value is 0.

+

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

@@ -1709,24 +1835,26 @@ typedef struct ErlIOVec { - intdriver_read_timer(ErlDrvPort port, unsigned long *time_left) - Read the time left before timeout + intdriver_read_timer(ErlDrvPort port, unsigned + long *time_left) + Read the time left before time-out. -

This function reads the current time of a timer, and places +

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.

+ milliseconds, before the time-out occurs.

+

The return value is 0.

 - void *driver_realloc(void *ptr, ErlDrvSizeT size) - Resize an allocated memory block + void * + driver_realloc(void *ptr, ErlDrvSizeT size) + Resize an allocated memory block. -

This function resizes a memory block, either in place, or by - allocating a new block, copying the data and freeing the old +

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.)

@@ -1735,120 +1863,132 @@ typedef struct ErlIOVec { - ErlDrvBinary *driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size) - Resize a driver binary + ErlDrvBinary * + driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size) + + Resize a driver binary. -

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

+

Resizes a driver binary, while keeping the data.

+

Returns the resized driver binary on success. Returns NULL + on failure (out of memory).

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 + intdriver_select(ErlDrvPort port, ErlDrvEvent + event, int mode, int on) + Provides 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 + when something has occurred asynchronously.

+

Parameter event 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 + On Windows, the Win32 API function WaitForMultipleObjects + is used. This places other restrictions on the event object; + see the Win32 SDK documentation.

+

Parameter on is to 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. +

Parameter mode 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).

+ events. A fired read event calls + + ready_input and a fired write event calls + + ready_output.

+ +

Some OS (Windows) do not differentiate between read and write + events. The callback 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 can still be using the event object + internally. To safely close an event object, call + driver_select with ERL_DRV_USE and on==0, which + clears all events. Then call + + stop_select when it is safe to close the event + object. ERL_DRV_USE is to be set together with the first event + for an event object. It is harmless to set ERL_DRV_USE + even if it already has been done. Clearing all events but keeping + ERL_DRV_USE set indicates that we are using the event + object and probably will set events for it again.

+ +

ERL_DRV_USE was added in Erlang/OTP R13. Old drivers still + work as before, but it is recommended to update them to use + ERL_DRV_USE and stop_select to ensure that event + objects are closed in a safe way.

+ +

The return value is 0, unless + ready_input/ready_output is NULL, in which case + it is -1.

 - intdriver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) - Send term data to other process than port owner process + intdriver_send_term(ErlDrvPort port, + ErlDrvTermData receiver, ErlDrvTermData* term, int n) + Send term data to other process than port owner process. + -

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

-

Also note that parameters of driver_send_term() - cannot be properly checked by the runtime system when - executed by arbitrary threads. This may cause the - driver_send_term() function not to fail when - it should.

- -

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

+ +

This function is deprecated. + Use + erl_drv_send_term instead.

+ + +

The parameters of this function + cannot be properly checked by the runtime system when + executed by arbitrary threads. This can cause the + function not to fail when it should.

+ +

Parameters term and n work as in + + erl_drv_output_term.

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

 - intdriver_set_timer(ErlDrvPort port, unsigned long time) - Set a timer to call the driver + intdriver_set_timer(ErlDrvPort port, unsigned + long time) + Set a timer to call the driver. -

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).

+

Sets a timer on the driver, which will count + down and call the driver when it is timed out. Parameter + time is the time in milliseconds before the timer expires.

+

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

+

Notice that only one timer exists on each driver instance; + setting a new timer replaces an older one.

+

Return value is 0, unless the timeout + driver function is NULL, in which case it is -1.

 - ErlDrvSizeTdriver_sizeq(ErlDrvPort port) - Return the size of the driver queue + ErlDrvSizeT + driver_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 +

Returns the number of bytes currently in the driver queue.

+

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

@@ -1856,585 +1996,523 @@ typedef struct ErlIOVec { - voiddriver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size) - Get information about the Erlang runtime system + voiddriver_system_info(ErlDrvSysInfo + *sys_info_ptr, size_t size) + Get information about the Erlang runtime system. -

This function will write information about the Erlang runtime - system into the - ErlDrvSysInfo +

Writes 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.

+ argument is to be the size of the + ErlDrvSysInfo + structure, that is, sizeof(ErlDrvSysInfo).

+

For information about specific fields, see + ErlDrvSysInfo.

 - - ErlDrvSizeTdriver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len) - Collect data segments into a buffer + + + ErlDrvSizeTdriver_vec_to_buf(ErlIOVec *ev, + char *buf, ErlDrvSizeT len) + Collect data segments into a buffer. -

This function collects several segments of data, referenced +

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 + process, it is faster to use + driver_outputv.

+

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

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

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.

- - - - - voiderl_drv_cond_broadcast(ErlDrvCond *cnd) - Broadcast on a condition variable + busy state of the port message queue.

+

The port message queue is set into a busy + state when the amount of command data queued on the + message queue reaches the high limit. The port + message queue is 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]. Notice 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 are automatically adjusted to be sane. That is, + the system adjusts values so that the low limit used is + lower than or equal to the high limit used. By default the high + limit is 8 kB and the low limit is 4 kB.

+

By passing a pointer to an integer variable containing + the value ERL_DRV_BUSY_MSGQ_READ_ONLY, the currently used + limit is 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 is + written to the internal limit. The internal limit is then + adjusted. After this the adjusted limit is 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 are + ERL_DRV_BUSY_MSGQ_DISABLED if this + feature has been disabled.

+

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

+

For information about busy port functionality, see + set_busy_port.

+ + + + + 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. -

+

Broadcasts on a condition variable. That is, if + other threads are waiting on the condition variable being + broadcast on, all of them are woken.

+

cnd is a pointer to a condition variable to broadcast on.

This function is thread-safe.

 - ErlDrvCond *erl_drv_cond_create(char *name) - Create a condition variable + ErlDrvCond *erl_drv_cond_create(char + *name) + Create a condition variable. -

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.

+

Creates a condition variable and returns a pointer to it.

+

name is a string identifying the created condition variable. + It is used to identify the condition variable in planned + future debug functionality.

+

Returns NULL on failure. The driver + creating the condition variable is responsibile for + destroying it before the driver is unloaded.

This function is thread-safe.

 - voiderl_drv_cond_destroy(ErlDrvCond *cnd) - Destroy a condition variable + 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(). -

-

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_cond_signal(ErlDrvCond *cnd) - Signal on a condition variable +

Destroys a condition variable previously created by + + erl_drv_cond_create.

+

cnd is a pointer to a condition variable to destroy.

+

This function is thread-safe.

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

Returns a pointer to the name of the condition.

+

cnd is a pointer to an initialized condition.

+ +

This function is intended for debugging purposes only.

+ + + + + + 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. -

+

Signals on a condition variable. That is, if + other threads are waiting on the condition variable being + signaled, one of them is woken.

+

cnd is a pointer to a condition variable to signal on.

This function is thread-safe.

 - voiderl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx) - Wait on a condition variable + voiderl_drv_cond_wait(ErlDrvCond *cnd, + ErlDrvMutex *mtx) + Wait on a condition variable. -

Arguments:

- - cnd - A pointer to a condition variable to wait on. - mtx - A pointer to a mutex to unlock while waiting. - - - -

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. -

+

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. + When the calling thread is woken, it locks the same mutex before + returning. That is, the mutex currently must be locked by + the calling thread when calling this function.

+

cnd is a pointer to a condition variable to wait on. + mtx is a pointer to a mutex to unlock while waiting.

+ +

erl_drv_cond_wait can return even if + no one has signaled or broadcast on the condition + variable. Code calling erl_drv_cond_wait is + always to be prepared for erl_drv_cond_wait + returning even if the condition that the thread was + waiting for has not 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.

 - interl_drv_consume_timeslice(ErlDrvPort port, int percent) + 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 + current driver callback call has consumed. -

Arguments:

+

Gives the runtime system a hint about how much CPU time the current + driver callback call has consumed since the last hint, or since the + the start of the callback if no previous hint has been given.

port Port handle of the executing port. percent Approximate consumed fraction of a full - time-slice in percent. + 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 - - -

Arguments:

+

The time is specified as a fraction, in percent, of a full time-slice + that a port is allowed to execute before it is to 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.

+

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

+

This function 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 is to 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 because of a port monopolizing a scheduler + thread. It can be used when dividing lengthy work into some repeated + driver callback calls, without the need to use threads.

+

See also the important warning + text at the beginning of this manual page.

+ + + + + ErlDrvTimeerl_drv_convert_time_unit(ErlDrvTime + val, ErlDrvTimeUnit from, ErlDrvTimeUnit to) + Convert time unit of a time 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.

- tid1 - A thread identifier. - tid2 - A thread identifier. + val + Value to convert time unit for. + from + Time unit of val. + to + Time unit of returned value. -

This function compares two thread identifiers for equality, - and returns 0 it they aren't equal, and - a value not equal to 0 if they are equal.

-

A Thread identifier may be reused very quickly after - a thread has terminated. Therefore, if a thread - corresponding to one of the involved thread identifiers - has terminated since the thread identifier was saved, - the result of erl_drv_equal_tids() might not give - the expected result. -

+

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

+

See also + ErlDrvTime and + + ErlDrvTimeUnit.

+ + + + + interl_drv_equal_tids(ErlDrvTid tid1, + ErlDrvTid tid2) + Compare thread identifiers for equality. + + +

Compares two thread identifiers, tid1 and tid2, + for equality.

+

Returns 0 it they are not equal, and a value not equal to + 0 if they are equal.

+ +

A thread identifier can be reused very quickly after + a thread has terminated. Therefore, if a thread + corresponding to one of the involved thread identifiers + has terminated since the thread identifier was saved, + the result of erl_drv_equal_tids does possibly not give + the expected result.

+

This function is thread-safe.

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

Arguments:

+

Retrieves the value of an environment variable.

key - A null terminated string containing the - name of the environment variable. + 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). - + A pointer to an integer. The integer is used both 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. -

+

When this function is called, *value_size is to 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, that is, no such environment variable was found, + a value < 0 is returned. When the size of the value + buffer is too small, a value > 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 + voiderl_drv_init_ack(ErlDrvPort port, + ErlDrvData res) + Acknowledge the start of the port. -

Arguments:

+

Acknowledges the start of the port.

port - The port handle of the port (driver instance) creating - doing the acknowledgment. + The port handle of the port (driver instance) + 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. + The result of the port initialization. Can be the same + values as the return value of + start, that is, 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 +

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 flag + ERL_DRV_FLAG_USE_INIT_ACK + has been set on the linked-in driver.

+ + + + + ErlDrvTime + erl_drv_monotonic_time(ErlDrvTimeUnit time_unit) + + Get Erlang monotonic time. + + +

Returns + Erlang monotonic time. Notice that negative values are + not uncommon.

+

time_unit is time unit of returned value.

+

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 + and + ErlDrvTimeUnit.

+ + + + + ErlDrvMutex *erl_drv_mutex_create(char + *name) + Create a mutex. -

Arguments:

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

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

+

Creates a mutex and returns a pointer to it.

+

name is a string identifying the created mutex. It is used + to identify the mutex in planned future debug functionality.

+

Returns NULL on failure. The driver creating the mutex is + responsible for destroying it before the driver is unloaded.

This function is thread-safe.

 - voiderl_drv_mutex_destroy(ErlDrvMutex *mtx) - Destroy a mutex + voiderl_drv_mutex_destroy(ErlDrvMutex + *mtx) + Destroy a mutex. -

Arguments:

- - mtx - A pointer to a mutex to destroy. - -

This function destroys a mutex previously created by - erl_drv_mutex_create(). - The mutex has to be in an unlocked state before being - destroyed. -

+

Destroys a mutex previously created by + + erl_drv_mutex_create. + The mutex must be in an unlocked state before it is destroyed.

+

mtx is a pointer to a mutex to destroy.

This function is thread-safe.

 - voiderl_drv_mutex_lock(ErlDrvMutex *mtx) - Lock a mutex + voiderl_drv_mutex_lock(ErlDrvMutex + *mtx) + Lock a mutex. -

Arguments:

- - mtx - A pointer to a mutex to lock. - -

This function locks a mutex. The calling thread will be - blocked until the mutex has been locked. A thread - which currently has locked the mutex may not lock - the same mutex again. -

-

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

+

Locks a mutex. The calling thread is blocked until the mutex has + been locked. A thread that has currently locked the mutex + cannot lock the same mutex again.

+

mtx is a pointer to a mutex to lock.

+ +

If you leave a mutex 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.

 - - 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_mutex_name(ErlDrvMutex + *mtx) + Get name of driver mutex. + + +

Returns a pointer to the mutex name.

+

mtx is a pointer to an initialized mutex.

+ +

This function is intended for debugging purposes only.

+ + + - interl_drv_mutex_trylock(ErlDrvMutex *mtx) - Try lock a mutex + interl_drv_mutex_trylock(ErlDrvMutex + *mtx) + Try lock a mutex. -

Arguments:

- - mtx - A pointer to a mutex to try to lock. - -

This function tries to lock a mutex. If successful 0, - is returned; otherwise, EBUSY is returned. A thread - which currently has locked the mutex may not try to - lock the same mutex again. -

-

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

+

Tries to lock a mutex. A thred that has currently locked the mutex + cannot try to lock the same mutex again.

+

mtx is a pointer to a mutex to try to lock.

+

Returns 0 on success, otherwise EBUSY.

+ +

If you leave a mutex 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_mutex_unlock(ErlDrvMutex *mtx) - Unlock a mutex + voiderl_drv_mutex_unlock(ErlDrvMutex + *mtx) + Unlock a mutex. -

Arguments:

- - mtx - A pointer to a mutex to unlock. - -

This function unlocks a mutex. The mutex currently has to be - locked by the calling thread. -

+

Unlocks a mutex. The mutex currently must be + locked by the calling thread.

+

mtx is a pointer to a mutex to unlock.

This function is thread-safe.

 - interl_drv_output_term(ErlDrvTermData port, ErlDrvTermData* term, int n) - Send term data from driver to port owner + interl_drv_output_term(ErlDrvTermData port, + ErlDrvTermData* term, int n) + Send term data from driver to port owner. -

This functions sends data in the special driver term +

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 + deliver term data from a driver. It 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 process + on the local node.

+ +

Parameter port is not + an ordinary port handle, but a port handle converted using + + driver_mk_port.

+ +

Parameter term 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), + term consists of 1-4 elements in the array. The + first term has a term type and then arguments. + Parameter port specifies the sending port.

+

Tuples, maps, and lists (except strings, see below) are built in reverse polish notation, so that to build a - tuple, the elements are given first, and then the tuple + tuple, the elements are specified 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.

+ + +

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

+ + +

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.

+ + +

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

+ +

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 + "splice" in a string in a list, a string specified this way is + not a list in itself, but the elements are elements of the surrounding list.

-Term type            Argument(s)
-===========================================
+Term type            Arguments
+---------            ---------
 ERL_DRV_NIL
 ERL_DRV_ATOM         ErlDrvTermData atom (from driver_mk_atom(char *string))
 ERL_DRV_INT          ErlDrvSInt integer
@@ -2447,398 +2525,345 @@ 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_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
-
+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. -

+ on a 64-bit runtime system and 32 bits wide on a 32-bit + runtime system. They were introduced in ERTS 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 + wide. They were introduced in ERTS 5.7.4.

+

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

+ +

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

-

The term ERL_DRV_STRING_CONS is a way to construct +

The ERL_DRV_STRING_CONS term 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 + 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 + must be specifed before ERL_DRV_STRING_CONS.

+

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

-

+/* to send [x, "abc", y] to the port: */ +ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("x"), + ERL_DRV_STRING, (ErlDrvTermData)"abc", 3, + ERL_DRV_ATOM, driver_mk_atom("y"), + ERL_DRV_NIL, + ERL_DRV_LIST, 4 +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]> +/* to send "abc123" to the port: */ +ErlDrvTermData spec[] = { + ERL_DRV_NIL, /* with STRING_CONS, the tail comes first */ + ERL_DRV_STRING_CONS, (ErlDrvTermData)"123", 3, + ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3, +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]>

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])); - ]]> - + term encoded with the + external format, + that is, a term that has been encoded by + + erlang:term_to_binary, + erl_interface, + and so on. + For example, if binp is a pointer to an ErlDrvBinary + that contains term {17, 4711} encoded with the + external format, + and you want to wrap it in a two-tuple with the tag my_tag, + that is, {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.

+ following call can 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. -

-

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

+ErlDrvPort port = ... +ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("key1"), + ERL_DRV_INT, 100, + ERL_DRV_ATOM, driver_mk_atom("key2"), + ERL_DRV_INT, 200, + ERL_DRV_INT, 300, + ERL_DRV_TUPLE, 2, + ERL_DRV_MAP, 2 +}; +erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]> +

If you want to pass a binary and do not already have the content + of the binary in an ErlDrvBinary, you can benefit from using + ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary + through + driver_alloc_binary and then pass the binary through + ERL_DRV_BINARY. The runtime system often allocates + 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 + ERTS 5.6.

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

 - interl_drv_putenv(const char *key, char *value) - Set the value of an environment variable + interl_drv_putenv(const char *key, char + *value) + Set the value of an environment variable. -

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. - -

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

-

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. -

+

Sets the value of an environment variable.

+

key is a NULL-terminated string containing the + name of the environment variable.

+

value is a NULL-terminated string containing the + new value of the environment variable.

+

Returns 0 on success, otherwise a value != 0.

+ +

The result of passing the empty string ("") as a value + is platform-dependent. On some platforms the variable value + 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.

 - ErlDrvRWLock *erl_drv_rwlock_create(char *name) - Create an rwlock + ErlDrvRWLock *erl_drv_rwlock_create(char + *name) + Create an rwlock. -

Arguments:

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

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

+

Creates an rwlock and returns a pointer to it.

+

name is a string identifying the created rwlock. + It is used to identify the rwlock in planned future + debug functionality.

+

Returns NULL on failure. The driver creating the rwlock + is responsible for destroying it before the driver is unloaded.

This function is thread-safe.

 - voiderl_drv_rwlock_destroy(ErlDrvRWLock *rwlck) - Destroy an rwlock + voiderl_drv_rwlock_destroy(ErlDrvRWLock + *rwlck) + Destroy an rwlock. -

Arguments:

- - rwlck - A pointer to an rwlock to destroy. - -

This function destroys an rwlock previously created by - erl_drv_rwlock_create(). - The rwlock has to be in an unlocked state before being destroyed. -

+

Destroys an rwlock previously created by + + erl_drv_rwlock_create. + The rwlock must be in an unlocked state before it is destroyed.

+

rwlck is a pointer to an rwlock to destroy.

This function is thread-safe.

 - - 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_rwlock_name(ErlDrvRWLock + *rwlck) + Get name of driver mutex. + + +

Returns a pointer to the name of the rwlock.

+

rwlck is a pointer to an initialized rwlock.

+ +

This function is intended for debugging purposes only.

+ + + - voiderl_drv_rwlock_rlock(ErlDrvRWLock *rwlck) - Read lock an rwlock + voiderl_drv_rwlock_rlock(ErlDrvRWLock + *rwlck) + Read lock an rwlock. -

Arguments:

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

This function read locks an rwlock. The calling thread will be - blocked until the rwlock has been read locked. A thread - which currently has read or read/write locked the rwlock may - not 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. -

+

Read locks an rwlock. The calling thread is + blocked until the rwlock has been read locked. A thread + that currently has read or read/write locked the rwlock + cannot lock the same rwlock again.

+

rwlck is a pointer to the rwlock to read lock.

+ +

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 + voiderl_drv_rwlock_runlock(ErlDrvRWLock + *rwlck) + Read unlock an rwlock. -

Arguments:

- - rwlck - A pointer to an rwlock to read unlock. - -

This function read unlocks an rwlock. The rwlock currently - has to be read locked by the calling thread. -

+

Read unlocks an rwlock. The rwlock currently must + be read locked by the calling thread.

+

rwlck is a pointer to an rwlock to read unlock.

This function is thread-safe.

 - voiderl_drv_rwlock_rwlock(ErlDrvRWLock *rwlck) - Read/Write lock an rwlock + voiderl_drv_rwlock_rwlock(ErlDrvRWLock + *rwlck) + Read/write lock an rwlock. -

Arguments:

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

This function read/write locks an rwlock. The calling thread - will be blocked until the rwlock has been read/write locked. - A thread which currently has read or read/write locked the - rwlock may not 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. -

+

Read/write locks an rwlock. The calling thread + is blocked until the rwlock has been read/write locked. + A thread that currently has read or read/write locked the + rwlock cannot lock the same rwlock again.

+

rwlck is a pointer to an rwlock to read/write lock.

+ +

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 + voiderl_drv_rwlock_rwunlock(ErlDrvRWLock + *rwlck) + Read/write unlock an rwlock. -

Arguments:

- - rwlck - A pointer to an rwlock to read/write unlock. - -

This function read/write unlocks an rwlock. The rwlock - currently has to be read/write locked by the calling thread. -

+

Read/write unlocks an rwlock. The rwlock currently must be + read/write locked by the calling thread.

+

rwlck is a pointer to an rwlock to read/write unlock.

This function is thread-safe.

 - interl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck) - Try to read lock an rwlock + 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. -

+

Tries to read lock an rwlock.

+

rwlck is a pointer to an rwlock to try to read lock.

+

Returns 0 on success, otherwise EBUSY. + A thread that currently has read or read/write locked the + rwlock cannot 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.

 - interl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck) - Try to read/write lock an rwlock + 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. -

+

Tries to read/write lock an rwlock. + A thread that currently has read or read/write locked the + rwlock cannot try to lock the same rwlock again.

+

rwlckis pointer to an rwlock to try to read/write lock.

+

Returns 0 om success, otherwise EBUSY.

+ +

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.

 - interl_drv_send_term(ErlDrvTermData port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) - Send term data to other process than port owner process + interl_drv_send_term(ErlDrvTermData port, + ErlDrvTermData receiver, ErlDrvTermData* term, int n) + Send term data to other process than port owner process. +

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().

+ other processes than the port owner process. Parameter + receiver specifies the process to receive the data.

+ +

Parameter port is not an ordinary port handle, but + a port handle converted using + + driver_mk_port.

+ +

Parameters port, term, and n work as in + + erl_drv_output_term.

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

 - voiderl_drv_set_os_pid(ErlDrvPort port, ErlDrvSInt pid) - Set the os_pid for the port + voiderl_drv_set_os_pid(ErlDrvPort port, + ErlDrvSInt pid) + Set the os_pid for the port. -

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 the os_pid seen when doing + + erlang:port_info/2 on this port.

+

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

 - interl_drv_thread_create(char *name, - ErlDrvTid *tid, - void * (*func)(void *), - void *arg, - ErlDrvThreadOpts *opts) - Create a thread + interl_drv_thread_create(char *name, ErlDrvTid + *tid, void * (*func)(void *), void *arg, ErlDrvThreadOpts + *opts) + Create a thread. -

Arguments:

+

Creates a new thread.

name - A string identifying the created thread. It will be used - to identify the thread in planned future debug - functionality. - + A string identifying the created thread. It is used to + identify the thread in planned future debug functionality. + tid A pointer to a thread identifier variable. func @@ -2848,377 +2873,348 @@ ERL_DRV_MAP int sz opts A pointer to thread options to use or NULL. -

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. -

-

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. -

+

Returns 0 on success, + otherwise an errno value is returned to indicate the error. + The newly created thread begins executing in the function pointed + to by func, and func is passed arg as + argument. When erl_drv_thread_create returns, the thread + identifier of the newly created thread is 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 + are used, otherwise the passed options are used.

+ +

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

+ +

The created thread terminates 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 is responsible for joining the + thread, through + erl_drv_thread_join, + before the driver is unloaded. "Detached" threads cannot be created, + that is, threads that do not need to be joined.

+ +

All created threads must 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 + most likely crashes when the driver code is unloaded.

+

This function is thread-safe.

 - voiderl_drv_thread_exit(void *exit_value) - Terminate calling thread + voiderl_drv_thread_exit(void + *exit_value) + Terminate calling thread. -

Arguments:

- - exit_value - A pointer to an exit value or NULL. - -

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(). -

+

Terminates the calling thread with the exit value passed as + argument. exit_value is a pointer to an exit value or + NULL.

+

You are only allowed to terminate threads created with + + erl_drv_thread_create.

+

The exit value can later be retrieved by another thread through + + erl_drv_thread_join.

This function is thread-safe.

 - interl_drv_thread_join(ErlDrvTid tid, void **exit_value) - Join with another thread + interl_drv_thread_join(ErlDrvTid tid, void + **exit_value) + Join with another thread. -

Arguments:

- - tid - The thread identifier of the thread to join. - exit_value - A pointer to a pointer to an exit value, or NULL. - -

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. -

+

Joins the calling thread with another thread, that is, + the calling thread is blocked until the thread identified by + tid has terminated.

+

tid is the thread identifier of the thread to join. + exit_value is a pointer to a pointer to an exit value, + or NULL.

+

Returns 0 on success, 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 + is ignored, otherwise the exit value of the terminated thread + is stored at *exit_value.

This function is thread-safe.

 - - char *erl_drv_thread_name(ErlDrvTid tid) - Get name of driver mutex. - - -

Arguments:

- - tid - A thread identifier. - -

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

- -

This function is intended for debugging purposes only.

- - - + + char *erl_drv_thread_name(ErlDrvTid + tid) + Get name of driver mutex. + + +

Returns a pointer to the name of the thread.

+

tid is a thread identifier.

+ +

This function is intended for debugging purposes only.

+ + + - ErlDrvThreadOpts *erl_drv_thread_opts_create(char *name) - Create thread options + 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(). -

+

Allocates and initializes a thread option structure.

+

name is a string identifying the created thread options. + It is used to identify the thread options in planned future debug + functionality.

+

Returns NULL on failure. A thread option + structure is used for passing options to + + erl_drv_thread_create. + If the structure is not modified before it is passed to + + erl_drv_thread_create, + the default values are used.

+ +

You are not allowed to allocate the + + ErlDrvThreadOpts + structure by yourself. It must 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 + void + erl_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(). -

+

Destroys thread options previously created by + + erl_drv_thread_opts_create.

+

opts is a pointer to thread options to destroy.

This function is thread-safe.

 - ErlDrvTiderl_drv_thread_self(void) - Get the thread identifier of the current thread + ErlDrvTid + erl_drv_thread_self(void) + Get the thread identifier of the current thread. -

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

+

Returns the thread identifier of the calling thread.

This function is thread-safe.

 - - ErlDrvTimeerl_drv_time_offset(ErlDrvTimeUnit time_unit) - Get current Time Offset - - -

Arguments:

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

Returns the current time offset between - Erlang monotonic time - and - Erlang system time - converted into the time_unit passed as argument.

-

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 - - - - - - void *erl_drv_tsd_get(ErlDrvTSDKey key) - Get thread specific data + + ErlDrvTimeerl_drv_time_offset(ErlDrvTimeUnit + time_unit) + Get current time offset. + + +

Returns the current time offset between + + Erlang monotonic time and + + Erlang system time + converted into the time_unit passed as argument.

+

time_unit is time unit of returned value.

+

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 and + + 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. -

+

Returns the thread-specific data + associated with key for the calling thread.

+

key is a thread-specific data key.

+

Returns NULL if no data has been associated + with key for the calling thread.

This function is thread-safe.

 - interl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key) - Create a thread specific data key + 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. -

+

Creates a thread-specific data key.

+

name is a string identifying the created key. It is used + to identify the key in planned future debug functionality.

+

key is a pointer to a thread-specific data key variable.

+

Returns 0 on success, otherwise an errno value is + returned to indicate the error. The driver creating the key is + responsible for 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 + 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. -

+

Destroys a thread-specific data key previously created by + + erl_drv_tsd_key_create. + All thread-specific data using this key in all threads + must be cleared (see + erl_drv_tsd_set) + before the call to erl_drv_tsd_key_destroy.

+

key is a thread-specific data key to 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 before 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 + 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. -

+

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 callback function, it must be cleared, that is, + set to NULL, before returning from the driver callback + function.

+

key is a thread-specific data key.

+

data is a pointer to data to associate with key + in the calling thread.

+ +

If you fail to clear thread-specific data in an + emulator thread before letting it out of your control, + you might never 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 + 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 +

Returns the atom name of the Erlang error, + given the error number in error. The error atoms are + einval, enoent, and so on. It can be used to make error terms from the driver.

 - intremove_driver_entry(ErlDrvEntry *de) - Remove a driver entry + 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.

+

Removes a driver entry de previously added with + + add_driver_entry.

+

Driver entries added by the erl_ddll Erlang interface + cannot be removed by using this interface.

 - voidset_busy_port(ErlDrvPort port, int on) - Signal or unsignal port as busy + 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 +

Sets and unsets the busy state of the port. If + on is non-zero, the port is set to busy. If it is 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 are suspended + if either the port or the port message queue + is busy. Suspended processes are resumed when neither the + port or 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 through + + erlang:port_command(Port, Data, [force]) + even if the driver has signaled that it is busy.

+

For information about busy port message queue functionality, see + + erl_drv_busy_msgq_limits.

+ + + + + 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.)

+

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

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 + 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 -

driver_entry(3), - erl_ddll(3), - erlang(3)

-

An Alternative Distribution Driver (ERTS User's - Guide Ch. 3)

+ See Also +

driver_entry(3), + erlang(3), + kernel:erl_ddll(3), + section How to Implement an Alternative + Carrier for the Erlang Distribution> in the User's Guide

-- cgit v1.2.3 From 606e660f898264ea75680532c076c56bbe855633 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Fri, 1 Jul 2016 17:32:51 +0200 Subject: erts: Review of documentation changes --- erts/doc/src/erl_driver.xml | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 69c3375858..8e83b74986 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -111,11 +111,10 @@ sent. This is convenient when matching on messages received from the port. (Although in the latest Erlang versions there is the binary syntax, which enables you to match on the beginning of - a binary.) - -

-

In the runtime system with SMP support, drivers are locked either - on driver level or port level (driver instance level). By default + a binary.)

+

In the runtime system with + SMP support, drivers are locked either on driver level + or port level (driver instance level). By default driver level locking will be used, that is, only one emulator thread will execute code in the driver at a time. If port level locking is used, multiple emulator threads can execute code in the driver @@ -979,7 +978,8 @@ int suggested_stack_size; memory, in which 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).

+ call to driver_free + (unless otherwise stated).

This function is thread-safe.

@@ -1008,7 +1008,7 @@ int suggested_stack_size; - longdriver_async (ErlDrvPort port, unsigned + 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. @@ -1076,7 +1076,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]> - unsigned intdriver_async_port_key (ErlDrvPort + unsigned intdriver_async_port_key(ErlDrvPort port) Calculate an async key from an ErlDrvPort. @@ -2215,7 +2215,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]> how to use this information. Implementations on some platforms can use other means to determine the consumed fraction of the time-slice. Lengthy driver callbacks should, regardless of - this frequently, call this function to determine if it is allowed + this, frequently call this function to determine if it is allowed to continue execution or not.

This function returns a non-zero value if the time-slice has been exhausted, and zero if the callback is @@ -2433,7 +2433,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]> Try lock a mutex. -

Tries to lock a mutex. A thred that has currently locked the mutex +

Tries to lock a mutex. A thread that has currently locked the mutex cannot try to lock the same mutex again.

mtx is a pointer to a mutex to try to lock.

Returns 0 on success, otherwise EBUSY.

@@ -2562,7 +2562,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] 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 specifed before ERL_DRV_STRING_CONS.

+ must be specified before ERL_DRV_STRING_CONS.

ERL_DRV_STRING constructs a string, and ends it. (So it is the same as ERL_DRV_NIL followed by ERL_DRV_STRING_CONS.)

@@ -2590,7 +2590,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] that is, a term that has been encoded by erlang:term_to_binary, - erl_interface, + erl_interface:ei(3), and so on. For example, if binp is a pointer to an ErlDrvBinary that contains term {17, 4711} encoded with the @@ -2803,7 +2803,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] A thread that currently has read or read/write locked the rwlock cannot try to lock the same rwlock again.

rwlckis pointer to an rwlock to try to read/write lock.

-

Returns 0 om success, otherwise EBUSY.

+

Returns 0 on success, otherwise EBUSY.

If you leave an rwlock locked in an emulator thread when you let the thread out of your control, you will -- cgit v1.2.3