EVOLUTION-MANAGER

Edit File: erl_driver.3

.TH erl_driver 3 "erts 5.10.4" "Ericsson AB" "C Library Functions" .SH NAME erl_driver \- API functions for an Erlang driver .SH DESCRIPTION .LP An Erlang driver is a library containing a set of native driver callback functions that the Erlang VM calls when certain events occur\&. There may be multiple instances of a driver, each instance is associated with an Erlang port\&. .LP .RS -4 .B Warning: .RE \fIUse this functionality with extreme care!\fR\& .LP 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 \fInot\fR\& 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\&. .RS 2 .TP 2 * A driver callback that crash will crash the whole VM\&. .LP .TP 2 * 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\&. .LP .TP 2 * A driver callback that do \fBlengthy work\fR\& 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\&. .LP .RE .LP As of erts version 5\&.5\&.3 the driver interface has been extended (see \fBextended marker\fR\&)\&. The extended interface introduce \fBversion management\fR\&, the possibility to pass capability flags (see \fBdriver flags\fR\&) to the runtime system at driver initialization, and some new driver API functions\&. .LP .RS -4 .B Note: .RE 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 \fB64-bit capable driver interface\&. \fR\& .LP The driver calls back to the emulator, using the API functions declared in \fIerl_driver\&.h\fR\&\&. They are used for outputting data from the driver, using timers, etc\&. .LP 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 \fIport\fR\& handle as an argument\&. This identifies the driver instance\&. Note that this port handle must be stored by the driver, it is not given when the driver is called from the emulator (see \fBdriver_entry\fR\&)\&. .LP Some of the functions take a parameter of type \fIErlDrvBinary\fR\&, a driver binary\&. It should be both allocated and freed by the caller\&. Using a binary directly avoids one extra copying of data\&. .LP Many of the output functions have a "header buffer", with \fIhbuf\fR\& and \fIhlen\fR\& 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 a binary\&.) .LP 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 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 \fIERL_DRV_FLAG_USE_PORT_LOCKING\fR\& \fBdriver flag\fR\& in the \fBdriver_entry\fR\& used by the driver\&. When port level locking is used it is the responsibility of the driver writer to synchronize all accesses to data shared by the ports (driver instances)\&. .LP 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 level locking is used\&. .LP .RS -4 .B Note: .RE 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 communication" is strongly discouraged\&. .LP Previously, in the runtime system without SMP support, specific driver call-backs were always called from the same thread\&. This is \fInot\fR\& 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 \fImost\fR\& drivers not be a problem, but it might\&. Drivers that depend on all call-backs being called in the same thread, \fIhave\fR\& to be rewritten before being used in the runtime system with SMP support\&. .LP .RS -4 .B Note: .RE Regardless of locking scheme used, calls to driver call-backs may be made from different threads\&. .LP Most functions in this API are \fInot\fR\& thread-safe, i\&.e\&., they may \fInot\fR\& 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 different threads\&. This, however, is not a problem for any function in this API, since the emulator has control over these threads\&. .LP .RS -4 .B Warning: .RE Functions not explicitly documented as thread safe are \fInot\fR\& thread safe\&. Also note that some functions are \fIonly\fR\& thread safe when used in a runtime system with SMP support\&. .LP 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 \fIunsafe\fR\& implementation at any time \fIwithout any notice\fR\& at all\&. .LP \fIOnly use functions explicitly documented as thread safe from arbitrary threads\&.\fR\& .LP As mentioned in the \fBwarning\fR\& 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 \fBtimeout callback\fR\& using zero timeouts\&. The \fB\fIerl_drv_consume_timeslice()\fR\&\fR\& 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\&. .SH "FUNCTIONALITY" .LP All functions that a driver needs to do with Erlang are performed through driver API functions\&. There are functions for the following functionality: .RS 2 .TP 2 .B Timer functions: Timer functions are used to control the timer that a driver may use\&. The timer will have the emulator call the \fBtimeout\fR\& entry function after a specified time\&. Only one timer is available for each driver instance\&. .TP 2 .B Queue handling: Every driver instance has an associated queue\&. This queue is a \fISysIOVec\fR\& that works as a buffer\&. It\&'s mostly used for the driver to buffer data that should 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 closed\&. This enables the driver to flush its buffers before closing\&. .RS 2 .LP The queue can be manipulated from arbitrary threads if a port data lock is used\&. See documentation of the \fBErlDrvPDL\fR\& type for more information\&. .RE .TP 2 .B 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 \fIopen_port/2\fR\&\&. 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\&. .TP 2 .B 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\&. .TP 2 .B 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\&. .TP 2 .B \fBMulti-threading\fR\&: 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: .RS 2 .TP 2 * \fBThreads\fR\& .LP .TP 2 * \fBMutexes\fR\& .LP .TP 2 * \fBCondition variables\fR\& .LP .TP 2 * \fBRead/Write locks\fR\& .LP .TP 2 * \fBThread specific data\fR\& .LP .RE .RS 2 .LP 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\&. .RE .RS 2 .LP 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\&. .RE .RS 2 .LP Note that there exists no "condition variable wait with timeout" in the Erlang driver thread API\&. This is due to issues with \fIpthread_cond_timedwait()\fR\&\&. 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\&. .RE .RS 2 .LP 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 \fBdriver_system_info()\fR\&\&. 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 \fBdriver_system_info()\fR\&\&. Also note that a lot of functions in the Erlang driver API are \fInot\fR\& thread-safe regardless of whether SMP support is enabled or not\&. If a function isn\&'t documented as thread-safe it is \fInot\fR\& thread-safe\&. .RE .RS 2 .LP \fINOTE\fR\&: When executing in an emulator thread, it is \fIvery important\fR\& that you unlock \fIall\fR\& locks you have locked before letting the thread out of your control; otherwise, you are \fIvery likely\fR\& 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\&. .RE .RS 2 .LP In the future there will probably be debug functionality integrated with the Erlang driver thread API\&. All functions that create entities take a \fIname\fR\& argument\&. Currently the \fIname\fR\& 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\&. .RE .TP 2 .B Adding / removing drivers: A driver can add and later remove drivers\&. .TP 2 .B Monitoring processes: A driver can monitor a process that does not own a port\&. .TP 2 .B \fBVersion management\fR\&: Version management is enabled for drivers that have set the \fBextended_marker\fR\& field of their \fBdriver_entry\fR\& to \fIERL_DRV_EXTENDED_MARKER\fR\&\&. \fIerl_driver\&.h\fR\& defines \fIERL_DRV_EXTENDED_MARKER\fR\&, \fIERL_DRV_EXTENDED_MAJOR_VERSION\fR\&, and \fIERL_DRV_EXTENDED_MINOR_VERSION\fR\&\&. \fIERL_DRV_EXTENDED_MAJOR_VERSION\fR\& will be incremented when driver incompatible changes are made to the Erlang runtime system\&. Normally it will suffice to recompile drivers when the \fIERL_DRV_EXTENDED_MAJOR_VERSION\fR\& has changed, but it could, under rare circumstances, mean that drivers have to be slightly modified\&. If so, this will of course be documented\&. \fIERL_DRV_EXTENDED_MINOR_VERSION\fR\& 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 refuse 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\&. .RS 2 .LP 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 \fBoutput\fR\&, \fBcontrol\fR\& and \fBcall\fR\& 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\&. .RE .RS 2 .LP 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! .RE .RS 2 .LP Also, the API driver functions \fIdriver_output*\fR\&, \fIdriver_vec_to_buf\fR\&, \fIdriver_alloc/realloc*\fR\& and the \fIdriver_*\fR\& 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 \fIint\fR\& all will work as before\&. .RE .RE .SH " REWRITES FOR 64-BIT DRIVER INTERFACE " .LP For erts-5\&.9 two new integer types \fBErlDrvSizeT\fR\& and \fBErlDrvSSizeT\fR\& were introduced that can hold 64-bit sizes if necessary\&. .LP To not update a driver and just 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 there \fIwill\fR\& be warnings and almost certainly crashes\&. So it is a BAD idea to postpone updating the driver and not fixing the warnings! .LP When recompiling with \fIgcc\fR\& use the \fI-Wstrict-prototypes\fR\& flag to get better warnings\&. Try to find a similar flag if you are using some other compiler\&. .LP Here follows a checklist for rewriting a pre erts-5\&.9 driver, most important first\&. .RS 2 .TP 2 .B Return types for driver callbacks: Rewrite driver callback \fI\fBcontrol\fR\&\fR\& to use return type \fIErlDrvSSizeT\fR\& instead of \fIint\fR\&\&. .RS 2 .LP Rewrite driver callback \fI\fBcall\fR\&\fR\& to use return type \fIErlDrvSSizeT\fR\& instead of \fIint\fR\&\&. .RE .LP .RS -4 .B Note: .RE These changes are essential to not 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\&. .TP 2 .B Arguments to driver callbacks: Driver callback \fI\fBoutput\fR\&\fR\& now gets \fIErlDrvSizeT\fR\& as 3rd argument instead of previously \fIint\fR\&\&. .RS 2 .LP Driver callback \fI\fBcontrol\fR\&\fR\& now gets \fIErlDrvSizeT\fR\& as 4th and 6th arguments instead of previously \fIint\fR\&\&. .RE .RS 2 .LP Driver callback \fI\fBcall\fR\&\fR\& now gets \fIErlDrvSizeT\fR\& as 4th and 6th arguments instead of previously \fIint\fR\&\&. .RE .RS 2 .LP 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 an \fIint\fR\& 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\&. .RE .LP .RS -4 .B Note: .RE 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\&. .TP 2 .B Larger \fIsize\fR\& field in \fIErlIOVec\fR\&: The \fIsize\fR\& field in \fB\fIErlIOVec\fR\&\fR\& has been changed to \fIErlDrvSizeT\fR\& from \fIint\fR\&\&. Check all code that use that field\&. .RS 2 .LP Automatic type casting probably makes these changes necessary only for a driver that encounters sizes larger than 32 bits\&. .RE .LP .RS -4 .B Note: .RE The \fIsize\fR\& 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\&. .TP 2 .B Arguments and return values in the driver API: Many driver API functions have changed argument type and/or return value to \fIErlDrvSizeT\fR\& from mostly \fIint\fR\&\&. Automatic type casting probably makes these changes necessary only for a driver that encounters sizes larger than 32 bits\&. .RS 2 .TP 2 .B \fBdriver_output\fR\&: 3rd argument .TP 2 .B \fBdriver_output2\fR\&: 3rd and 5th arguments .TP 2 .B \fBdriver_output_binary\fR\&: 3rd 5th and 6th arguments .TP 2 .B \fBdriver_outputv\fR\&: 3rd and 5th arguments .TP 2 .B \fBdriver_vec_to_buf\fR\&: 3rd argument and return value .TP 2 .B \fBdriver_alloc\fR\&: 1st argument .TP 2 .B \fBdriver_realloc\fR\&: 2nd argument .TP 2 .B \fBdriver_alloc_binary\fR\&: 1st argument .TP 2 .B \fBdriver_realloc_binary\fR\&: 2nd argument .TP 2 .B \fBdriver_enq\fR\&: 3rd argument .TP 2 .B \fBdriver_pushq\fR\&: 3rd argument .TP 2 .B \fBdriver_deq\fR\&: 2nd argument and return value .TP 2 .B \fBdriver_sizeq\fR\&: return value .TP 2 .B \fBdriver_enq_bin\fR\&: 3rd and 4th argument .TP 2 .B \fBdriver_pushq_bin\fR\&: 3rd and 4th argument .TP 2 .B \fBdriver_enqv\fR\&: 3rd argument .TP 2 .B \fBdriver_pushqv\fR\&: 3rd argument .TP 2 .B \fBdriver_peekqv\fR\&: return value .RE .LP .RS -4 .B Note: .RE 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\&. .RE .SH "DATA TYPES" .RS 2 .TP 2 .B ErlDrvSizeT: An unsigned integer type to be used as \fIsize_t\fR\& .TP 2 .B ErlDrvSSizeT: A signed integer type the size of \fIErlDrvSizeT\fR\& .TP 2 .B ErlDrvSysInfo: .LP .nf typedef struct ErlDrvSysInfo { int driver_major_version; int driver_minor_version; char *erts_version; char *otp_release; int thread_support; int smp_support; int async_threads; int scheduler_threads; int nif_major_version; int nif_minor_version; } ErlDrvSysInfo; .fi .RS 2 .LP The \fIErlDrvSysInfo\fR\& structure is used for storage of information about the Erlang runtime system\&. \fBdriver_system_info()\fR\& will write the system information when passed a reference to a \fIErlDrvSysInfo\fR\& structure\&. A description of the fields in the structure follows: .RE .RS 2 .TP 2 .B \fIdriver_major_version\fR\&: The value of \fBERL_DRV_EXTENDED_MAJOR_VERSION\fR\& when the runtime system was compiled\&. This value is the same as the value of \fBERL_DRV_EXTENDED_MAJOR_VERSION\fR\& used when compiling the driver; otherwise, the runtime system would have refused to load the driver\&. .TP 2 .B \fIdriver_minor_version\fR\&: The value of \fBERL_DRV_EXTENDED_MINOR_VERSION\fR\& when the runtime system was compiled\&. This value might differ from the value of \fBERL_DRV_EXTENDED_MINOR_VERSION\fR\& used when compiling the driver\&. .TP 2 .B \fIerts_version\fR\&: A string containing the version number of the runtime system (the same as returned by \fBerlang:system_info(version)\fR\&)\&. .TP 2 .B \fIotp_release\fR\&: A string containing the OTP release number (the same as returned by \fBerlang:system_info(otp_release)\fR\&)\&. .TP 2 .B \fIthread_support\fR\&: A value \fI!= 0\fR\& if the runtime system has thread support; otherwise, \fI0\fR\&\&. .TP 2 .B \fIsmp_support\fR\&: A value \fI!= 0\fR\& if the runtime system has SMP support; otherwise, \fI0\fR\&\&. .TP 2 .B \fIasync_threads\fR\&: The number of async threads in the async thread pool used by \fBdriver_async()\fR\& (the same as returned by \fBerlang:system_info(thread_pool_size)\fR\&)\&. .TP 2 .B \fIscheduler_threads\fR\&: The number of scheduler threads used by the runtime system (the same as returned by \fBerlang:system_info(schedulers)\fR\&)\&. .TP 2 .B \fInif_major_version\fR\&: The value of \fIERL_NIF_MAJOR_VERSION\fR\& when the runtime system was compiled\&. .TP 2 .B \fInif_minor_version\fR\&: The value of \fIERL_NIF_MINOR_VERSION\fR\& when the runtime system was compiled\&. .RE .TP 2 .B ErlDrvBinary: .LP .nf typedef struct ErlDrvBinary { ErlDrvSint orig_size; char orig_bytes[]; } ErlDrvBinary; .fi .RS 2 .LP The \fIErlDrvBinary\fR\& structure is a binary, as sent between the emulator and the driver\&. All binaries are reference counted; when \fIdriver_binary_free\fR\& is called, the reference count is decremented, when it reaches zero, the binary is deallocated\&. The \fIorig_size\fR\& is the size of the binary, and \fIorig_bytes\fR\& is the buffer\&. The \fIErlDrvBinary\fR\& does not have a fixed size, its size is \fIorig_size + 2 * sizeof(int)\fR\&\&. .RE .LP .RS -4 .B Note: .RE The \fIrefc\fR\& field has been removed\&. The reference count of an \fIErlDrvBinary\fR\& is now stored elsewhere\&. The reference count of an \fIErlDrvBinary\fR\& can be accessed via \fBdriver_binary_get_refc()\fR\&, \fBdriver_binary_inc_refc()\fR\&, and \fBdriver_binary_dec_refc()\fR\&\&. .RS 2 .LP Some driver calls, such as \fIdriver_enq_binary\fR\&, increment the driver reference count, and others, such as \fIdriver_deq\fR\& decrement it\&. .RE .RS 2 .LP Using a driver binary instead of a normal buffer, is often faster, since the emulator doesn\&'t need to copy the data, only the pointer is used\&. .RE .RS 2 .LP A driver binary allocated in the driver, with \fIdriver_alloc_binary\fR\&, should be freed in the driver (unless otherwise stated), with \fIdriver_free_binary\fR\&\&. (Note that this doesn\&'t necessarily deallocate it, if the driver is still referred in the emulator, the ref-count will not go to zero\&.) .RE .RS 2 .LP Driver binaries are used in the \fIdriver_output2\fR\& and \fIdriver_outputv\fR\& calls, and in the queue\&. Also the driver call-back \fBoutputv\fR\& uses driver binaries\&. .RE .RS 2 .LP 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 \fBstop\fR\& call-back, with \fIdriver_free_binary\fR\&\&. .RE .RS 2 .LP 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\&. .RE .RS 2 .LP Since erts version 5\&.5 (OTP release R11B), orig_bytes is guaranteed to be properly aligned for storage of an array of doubles (usually 8-byte aligned)\&. .RE .TP 2 .B ErlDrvData: The \fIErlDrvData\fR\& is a handle to driver-specific data, passed to the driver call-backs\&. It is a pointer, and is most often type cast to a specific pointer in the driver\&. .TP 2 .B SysIOVec: This is a system I/O vector, as used by \fIwritev\fR\& on unix and \fIWSASend\fR\& on Win32\&. It is used in \fIErlIOVec\fR\&\&. .TP 2 .B ErlIOVec: .LP .nf typedef struct ErlIOVec { int vsize; ErlDrvSizeT size; SysIOVec* iov; ErlDrvBinary** binv; } ErlIOVec; .fi .RS 2 .LP The I/O vector used by the emulator and drivers, is a list of binaries, with a \fISysIOVec\fR\& pointing to the buffers of the binaries\&. It is used in \fIdriver_outputv\fR\& and the \fBoutputv\fR\& driver call-back\&. Also, the driver queue is an \fIErlIOVec\fR\&\&. .RE .TP 2 .B ErlDrvMonitor: When a driver creates a monitor for a process, a \fIErlDrvMonitor\fR\& 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)\&. .RS 2 .LP The driver writer should provide the memory for storing the monitor when calling \fBdriver_monitor_process\fR\&\&. The address of the data is not stored outside of the driver, so the \fIErlDrvMonitor\fR\& can be used as any other datum, it can be copied, moved in memory, forgotten etc\&. .RE .TP 2 .B ErlDrvNowData: The \fIErlDrvNowData\fR\& structure holds a timestamp consisting of three values measured from some arbitrary point in the past\&. The three structure members are: .RS 2 .TP 2 .B megasecs: The number of whole megaseconds elapsed since the arbitrary point in time .TP 2 .B secs: The number of whole seconds elapsed since the arbitrary point in time .TP 2 .B microsecs: The number of whole microseconds elapsed since the arbitrary point in time .RE .TP 2 .B 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 associates with the port data lock is the driver queue\&. .RS 2 .LP 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 create the port data lock by calling \fBdriver_pdl_create()\fR\&\&. \fINOTE\fR\&: 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 \fBdriver_pdl_lock()\fR\&, and \fBdriver_pdl_unlock()\fR\&\&. .RE .RS 2 .LP 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, or canceled\&. Besides this, it is the responsibility of the driver to ensure 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 \fBdriver_pdl_get_refc()\fR\&, \fBdriver_pdl_inc_refc()\fR\&, and \fBdriver_pdl_dec_refc()\fR\&\&. .RE .TP 2 .B ErlDrvTid: Thread identifier\&. .RS 2 .LP See also: \fBerl_drv_thread_create()\fR\&, \fBerl_drv_thread_exit()\fR\&, \fBerl_drv_thread_join()\fR\&, \fBerl_drv_thread_self()\fR\&, and \fBerl_drv_equal_tids()\fR\&\&. .RE .TP 2 .B ErlDrvThreadOpts: .LP .nf int suggested_stack_size; .fi .RS 2 .LP Thread options structure passed to \fBerl_drv_thread_create()\fR\&\&. Currently the following fields exist: .RE .RS 2 .TP 2 .B suggested_stack_size: A suggestion, in kilo-words, on how large a stack to use\&. A value less than zero means default size\&. .RE .RS 2 .LP See also: \fBerl_drv_thread_opts_create()\fR\&, \fBerl_drv_thread_opts_destroy()\fR\&, and \fBerl_drv_thread_create()\fR\&\&. .RE .TP 2 .B ErlDrvMutex: Mutual exclusion lock\&. Used for synchronizing access to shared data\&. Only one thread at a time can lock a mutex\&. .RS 2 .LP See also: \fBerl_drv_mutex_create()\fR\&, \fBerl_drv_mutex_destroy()\fR\&, \fBerl_drv_mutex_lock()\fR\&, \fBerl_drv_mutex_trylock()\fR\&, and \fBerl_drv_mutex_unlock()\fR\&\&. .RE .TP 2 .B 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\&. .RS 2 .LP See also: \fBerl_drv_cond_create()\fR\&, \fBerl_drv_cond_destroy()\fR\&, \fBerl_drv_cond_signal()\fR\&, \fBerl_drv_cond_broadcast()\fR\&, and \fBerl_drv_cond_wait()\fR\&\&. .RE .TP 2 .B 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\&. .RS 2 .LP See also: \fBerl_drv_rwlock_create()\fR\&, \fBerl_drv_rwlock_destroy()\fR\&, \fBerl_drv_rwlock_rlock()\fR\&, \fBerl_drv_rwlock_tryrlock()\fR\&, \fBerl_drv_rwlock_runlock()\fR\&, \fBerl_drv_rwlock_rwlock()\fR\&, \fBerl_drv_rwlock_tryrwlock()\fR\&, and \fBerl_drv_rwlock_rwunlock()\fR\&\&. .RE .TP 2 .B ErlDrvTSDKey: Key which thread specific data can be associated with\&. .RS 2 .LP See also: \fBerl_drv_tsd_key_create()\fR\&, \fBerl_drv_tsd_key_destroy()\fR\&, \fBerl_drv_tsd_set()\fR\&, and \fBerl_drv_tsd_get()\fR\&\&. .RE .RE .SH EXPORTS .LP .B void driver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size) .br .RS .LP This function will write information about the Erlang runtime system into the \fBErlDrvSysInfo\fR\& structure referred to by the first argument\&. The second argument should be the size of the \fBErlDrvSysInfo\fR\& structure, i\&.e\&., \fIsizeof(ErlDrvSysInfo)\fR\&\&. .LP See the documentation of the \fBErlDrvSysInfo\fR\& structure for information about specific fields\&. .RE .LP .B int driver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len) .br .RS .LP The \fIdriver_output\fR\& 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\&. .LP 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\&.) .LP The parameter \fIbuf\fR\& points to the data to send, and \fIlen\fR\& is the number of bytes\&. .LP 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\&.) .RE .LP .B int driver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len) .br .RS .LP The \fIdriver_output2\fR\& function first sends \fIhbuf\fR\& (length in \fIhlen\fR\&) data as a list, regardless of port settings\&. Then \fIbuf\fR\& is sent as a binary or list\&. E\&.g\&. if \fIhlen\fR\& is 3 then the port owner process will receive \fI[H1, H2, H3 | T]\fR\&\&. .LP The point of sending data as a list header, is to facilitate matching on the data received\&. .LP The return value is 0 for normal use\&. .RE .LP .B int driver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len) .br .RS .LP This function sends data to port owner process from a driver binary, it has a header buffer (\fIhbuf\fR\& and \fIhlen\fR\&) just like \fIdriver_output2\fR\&\&. The \fIhbuf\fR\& parameter can be \fINULL\fR\&\&. .LP The parameter \fIoffset\fR\& is an offset into the binary and \fIlen\fR\& is the number of bytes to send\&. .LP Driver binaries are created with \fIdriver_alloc_binary\fR\&\&. .LP The data in the header is sent as a list and the binary as an Erlang binary in the tail of the list\&. .LP E\&.g\&. if \fIhlen\fR\& is 2, then the port owner process will receive \fI[H1, H2 | <<T>>]\fR\&\&. .LP The return value is 0 for normal use\&. .LP 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\&. .RE .LP .B int driver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip) .br .RS .LP This function sends data from an IO vector, \fIev\fR\&, to the port owner process\&. It has a header buffer (\fIhbuf\fR\& and \fIhlen\fR\&), just like \fIdriver_output2\fR\&\&. .LP The \fIskip\fR\& parameter is a number of bytes to skip of the \fIev\fR\& vector from the head\&. .LP You get vectors of \fIErlIOVec\fR\& type from the driver queue (see below), and the \fBoutputv\fR\& driver entry function\&. You can also make them yourself, if you want to send several \fIErlDrvBinary\fR\& buffers at once\&. Often it is faster to use \fIdriver_output\fR\& or \fIdriver_output_binary\fR\&\&. .LP E\&.g\&. if \fIhlen\fR\& is 2 and \fIev\fR\& points to an array of three binaries, the port owner process will receive \fI[H1, H2, <<B1>>, <<B2>> | <<B3>>]\fR\&\&. .LP The return value is 0 for normal use\&. .LP The comment for \fIdriver_output_binary\fR\& applies for \fIdriver_outputv\fR\& too\&. .RE .LP .B ErlDrvSizeT driver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len) .br .RS .LP This function collects several segments of data, referenced by \fIev\fR\&, by copying them in order to the buffer \fIbuf\fR\&, of the size \fIlen\fR\&\&. .LP If the data is to be sent from the driver to the port owner process, it is faster to use \fIdriver_outputv\fR\&\&. .LP The return value is the space left in the buffer, i\&.e\&. if the \fIev\fR\& contains less than \fIlen\fR\& bytes it\&'s the difference, and if \fIev\fR\& contains \fIlen\fR\& 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\&. .RE .LP .B int driver_set_timer(ErlDrvPort port, unsigned long time) .br .RS .LP This function sets a timer on the driver, which will count down and call the driver when it is timed out\&. The \fItime\fR\& parameter is the time in milliseconds before the timer expires\&. .LP When the timer reaches 0 and expires, the driver entry function \fBtimeout\fR\& is called\&. .LP Note that there is only one timer on each driver instance; setting a new timer will replace an older one\&. .LP Return value is 0 (-1 only when the \fItimeout\fR\& driver function is \fINULL\fR\&)\&. .RE .LP .B int driver_cancel_timer(ErlDrvPort port) .br .RS .LP This function cancels a timer set with \fIdriver_set_timer\fR\&\&. .LP The return value is 0\&. .RE .LP .B int driver_read_timer(ErlDrvPort port, unsigned long *time_left) .br .RS .LP This function reads the current time of a timer, and places the result in \fItime_left\fR\&\&. This is the time in milliseconds, before the timeout will occur\&. .LP The return value is 0\&. .RE .LP .B int driver_get_now(ErlDrvNowData *now) .br .RS .LP This function reads a timestamp into the memory pointed to by the parameter \fInow\fR\&\&. See the description of \fBErlDrvNowData\fR\& for specification of its fields\&. .LP The return value is 0 unless the \fInow\fR\& pointer is not valid, in which case it is < 0\&. .RE .LP .B int driver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on) .br .RS .LP 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\&. .LP The \fIevent\fR\& argument identifies an OS-specific event object\&. On Unix systems, the functions \fIselect\fR\&/\fIpoll\fR\& are used\&. The event object must be a socket or pipe (or other object that \fIselect\fR\&/\fIpoll\fR\& can use)\&. On windows, the Win32 API function \fIWaitForMultipleObjects\fR\& is used\&. This places other restrictions on the event object\&. Refer to the Win32 SDK documentation\&. .LP The \fIon\fR\& parameter should be \fI1\fR\& for setting events and \fI0\fR\& for clearing them\&. .LP The \fImode\fR\& argument is a bitwise-or combination of \fIERL_DRV_READ\fR\&, \fIERL_DRV_WRITE\fR\& and \fIERL_DRV_USE\fR\&\&. The first two specify whether to wait for read events and/or write events\&. A fired read event will call \fBready_input\fR\& while a fired write event will call \fBready_output\fR\&\&. .LP .RS -4 .B Note: .RE 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 \fImode\fR\&\&. .LP \fIERL_DRV_USE\fR\& 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 \fIdriver_select\fR\& has returned\&. Another thread may still be using the event object internally\&. To safely close an event object call \fIdriver_select\fR\& with \fIERL_DRV_USE\fR\& and \fIon==0\fR\&\&. That will clear all events and then call \fBstop_select\fR\& when it is safe to close the event object\&. \fIERL_DRV_USE\fR\& should be set together with the first event for an event object\&. It is harmless to set \fIERL_DRV_USE\fR\& even though it already has been done\&. Clearing all events but keeping \fIERL_DRV_USE\fR\& set will indicate that we are using the event object and probably will set events for it again\&. .LP .RS -4 .B Note: .RE 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 \fIERL_DRV_USE\fR\& and \fIstop_select\fR\& to make sure that event objects are closed in a safe way\&. .LP The return value is 0 (failure, -1, only if the \fIready_input\fR\&/\fIready_output\fR\& is \fINULL\fR\&)\&. .RE .LP .B void *driver_alloc(ErlDrvSizeT size) .br .RS .LP This function allocates a memory block of the size specified in \fIsize\fR\&, and returns it\&. This only fails on out of memory, in that case \fINULL\fR\& is returned\&. (This is most often a wrapper for \fImalloc\fR\&)\&. .LP Memory allocated must be explicitly freed with a corresponding call to \fIdriver_free\fR\& (unless otherwise stated)\&. .LP This function is thread-safe\&. .RE .LP .B void *driver_realloc(void *ptr, ErlDrvSizeT size) .br .RS .LP 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), \fINULL\fR\& is returned\&. (This is most often a wrapper for \fIrealloc\fR\&\&.) .LP This function is thread-safe\&. .RE .LP .B void driver_free(void *ptr) .br .RS .LP This function frees the memory pointed to by \fIptr\fR\&\&. The memory should have been allocated with \fIdriver_alloc\fR\&\&. All allocated memory should be deallocated, just once\&. There is no garbage collection in drivers\&. .LP This function is thread-safe\&. .RE .LP .B ErlDrvBinary *driver_alloc_binary(ErlDrvSizeT size) .br .RS .LP This function allocates a driver binary with a memory block of at least \fIsize\fR\& 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 \fIdriver_free_binary\fR\& (unless otherwise stated)\&. .LP Note that a driver binary has an internal reference counter, this means that calling \fIdriver_free_binary\fR\& it may not actually dispose of it\&. If it\&'s sent to the emulator, it may be referenced there\&. .LP The driver binary has a field, \fIorig_bytes\fR\&, which marks the start of the data in the binary\&. .LP This function is thread-safe\&. .RE .LP .B ErlDrvBinary *driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size) .br .RS .LP This function resizes a driver binary, while keeping the data\&. The resized driver binary is returned\&. On failure (out of memory), \fINULL\fR\& is returned\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .RE .LP .B void driver_free_binary(ErlDrvBinary *bin) .br .RS .LP This function frees a driver binary \fIbin\fR\&, allocated previously with \fIdriver_alloc_binary\fR\&\&. Since binaries in Erlang are reference counted, the binary may still be around\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .RE .LP .B long driver_binary_get_refc(ErlDrvBinary *bin) .br .RS .LP Returns current reference count on \fIbin\fR\&\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .RE .LP .B long driver_binary_inc_refc(ErlDrvBinary *bin) .br .RS .LP Increments the reference count on \fIbin\fR\& and returns the reference count reached after the increment\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .RE .LP .B long driver_binary_dec_refc(ErlDrvBinary *bin) .br .RS .LP Decrements the reference count on \fIbin\fR\& and returns the reference count reached after the decrement\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .LP .RS -4 .B Note: .RE You should normally decrement the reference count of a driver binary by calling \fBdriver_free_binary()\fR\&\&. \fIdriver_binary_dec_refc()\fR\& does \fInot\fR\& free the binary if the reference count reaches zero\&. \fIOnly\fR\& use \fIdriver_binary_dec_refc()\fR\& when you are sure \fInot\fR\& to reach a reference count of zero\&. .RE .LP .B int driver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len) .br .RS .LP This function enqueues data in the driver queue\&. The data in \fIbuf\fR\& is copied (\fIlen\fR\& bytes) and placed at the end of the driver queue\&. The driver queue is normally used in a FIFO way\&. .LP 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\&. .LP When the queue contains data, the driver won\&'t close, until the queue is empty\&. .LP The return value is 0\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B int driver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len) .br .RS .LP This function puts data at the head of the driver queue\&. The data in \fIbuf\fR\& is copied (\fIlen\fR\& bytes) and placed at the beginning of the queue\&. .LP The return value is 0\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B ErlDrvSizeT driver_deq(ErlDrvPort port, ErlDrvSizeT size) .br .RS .LP This function dequeues data by moving the head pointer forward in the driver queue by \fIsize\fR\& bytes\&. The data in the queue will be deallocated\&. .LP The return value is the number of bytes remaining in the queue or -1 on failure\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B ErlDrvSizeT driver_sizeq(ErlDrvPort port) .br .RS .LP This function returns the number of bytes currently in the driver queue\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B int driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) .br .RS .LP This function enqueues a driver binary in the driver queue\&. The data in \fIbin\fR\& at \fIoffset\fR\& with length \fIlen\fR\& is placed at the end of the queue\&. This function is most often faster than \fIdriver_enq\fR\&, because the data doesn\&'t have to be copied\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .LP The return value is 0\&. .RE .LP .B int driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len) .br .RS .LP This function puts data in the binary \fIbin\fR\&, at \fIoffset\fR\& with length \fIlen\fR\& at the head of the driver queue\&. It is most often faster than \fIdriver_pushq\fR\&, because the data doesn\&'t have to be copied\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .LP The return value is 0\&. .RE .LP .B ErlDrvSizeT driver_peekqv(ErlDrvPort port, ErlIOVec *ev) .br .RS .LP This function retrieves the driver queue into a supplied \fIErlIOVec\fR\& \fIev\fR\&\&. It also returns the queue size\&. This is one of two ways to get data out of the queue\&. .LP If \fIev\fR\& is \fINULL\fR\& all ones i\&.e\&. \fI-1\fR\& type cast to \fIErlDrvSizeT\fR\& is returned\&. .LP Nothing is removed from the queue by this function, that must be done with \fIdriver_deq\fR\&\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B SysIOVec *driver_peekq(ErlDrvPort port, int *vlen) .br .RS .LP This function retrieves the driver queue as a pointer to an array of \fISysIOVec\fR\&s\&. It also returns the number of elements in \fIvlen\fR\&\&. This is one of two ways to get data out of the queue\&. .LP Nothing is removed from the queue by this function, that must be done with \fIdriver_deq\fR\&\&. .LP The returned array is suitable to use with the Unix system call \fIwritev\fR\&\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B int driver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip) .br .RS .LP This function enqueues the data in \fIev\fR\&, skipping the first \fIskip\fR\& bytes of it, at the end of the driver queue\&. It is faster than \fIdriver_enq\fR\&, because the data doesn\&'t have to be copied\&. .LP The return value is 0\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B int driver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip) .br .RS .LP This function puts the data in \fIev\fR\&, skipping the first \fIskip\fR\& bytes of it, at the head of the driver queue\&. It is faster than \fIdriver_pushq\fR\&, because the data doesn\&'t have to be copied\&. .LP The return value is 0\&. .LP This function can be called from an arbitrary thread if a \fBport data lock\fR\& associated with the \fIport\fR\& is locked by the calling thread during the call\&. .RE .LP .B ErlDrvPDL driver_pdl_create(ErlDrvPort port) .br .RS .LP This function creates a port data lock associated with the \fIport\fR\&\&. \fINOTE\fR\&: Once a port data lock has been created, it has to be locked during all operations on the driver queue of the \fIport\fR\&\&. .LP On success a newly created port data lock is returned\&. On failure \fINULL\fR\& is returned\&. \fIdriver_pdl_create()\fR\& will fail if \fIport\fR\& is invalid or if a port data lock already has been associated with the \fIport\fR\&\&. .RE .LP .B void driver_pdl_lock(ErlDrvPDL pdl) .br .RS .LP This function locks the port data lock passed as argument (\fIpdl\fR\&)\&. .LP This function is thread-safe\&. .RE .LP .B void driver_pdl_unlock(ErlDrvPDL pdl) .br .RS .LP This function unlocks the port data lock passed as argument (\fIpdl\fR\&)\&. .LP This function is thread-safe\&. .RE .LP .B long driver_pdl_get_refc(ErlDrvPDL pdl) .br .RS .LP This function returns the current reference count of the port data lock passed as argument (\fIpdl\fR\&)\&. .LP This function is thread-safe\&. .RE .LP .B long driver_pdl_inc_refc(ErlDrvPDL pdl) .br .RS .LP This function increments the reference count of the port data lock passed as argument (\fIpdl\fR\&)\&. .LP The current reference count after the increment has been performed is returned\&. .LP This function is thread-safe\&. .RE .LP .B long driver_pdl_dec_refc(ErlDrvPDL pdl) .br .RS .LP This function decrements the reference count of the port data lock passed as argument (\fIpdl\fR\&)\&. .LP The current reference count after the decrement has been performed is returned\&. .LP This function is thread-safe\&. .RE .LP .B int driver_monitor_process(ErlDrvPort port, ErlDrvTermData process, ErlDrvMonitor *monitor) .br .RS .LP Start monitoring a process from a driver\&. When a process is monitored, a process exit will result in a call to the provided \fBprocess_exit\fR\& call-back in the \fBErlDrvEntry\fR\& structure\&. The \fIErlDrvMonitor\fR\& structure is filled in, for later removal or compare\&. .LP The \fIprocess\fR\& parameter should be the return value of an earlier call to \fBdriver_caller\fR\& or \fBdriver_connected\fR\& call\&. .LP The function returns 0 on success, < 0 if no call-back is provided and > 0 if the process is no longer alive\&. .RE .LP .B int driver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor) .br .RS .LP This function cancels a monitor created earlier\&. .LP The function returns 0 if a monitor was removed and > 0 if the monitor did no longer exist\&. .RE .LP .B ErlDrvTermData driver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor) .br .RS .LP The function returns the process id associated with a living monitor\&. It can be used in the \fIprocess_exit\fR\& call-back to get the process identification for the exiting process\&. .LP The function returns \fIdriver_term_nil\fR\& if the monitor no longer exists\&. .RE .LP .B int driver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2) .br .RS .LP This function is used to compare two \fIErlDrvMonitor\fR\&s\&. It can also be used to imply some artificial order on monitors, for whatever reason\&. .LP The function returns 0 if \fImonitor1\fR\& and \fImonitor2\fR\& are equal, < 0 if \fImonitor1\fR\& is less than \fImonitor2\fR\& and > 0 if \fImonitor1\fR\& is greater than \fImonitor2\fR\&\&. .RE .LP .B void add_driver_entry(ErlDrvEntry *de) .br .RS .LP This function adds a driver entry to the list of drivers known by Erlang\&. The \fBinit\fR\& function of the \fIde\fR\& parameter is called\&. .LP .RS -4 .B Note: .RE 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\&. \fI\&.so\fR\& file) as a normal dynamically loaded driver (loaded with the \fIerl_ddll\fR\& interface), the caller should call \fBdriver_lock_driver\fR\& before adding driver entries\&. .LP Use of this function is generally deprecated\&. .RE .LP .B int remove_driver_entry(ErlDrvEntry *de) .br .RS .LP This function removes a driver entry \fIde\fR\& previously added with \fIadd_driver_entry\fR\&\&. .LP Driver entries added by the \fIerl_ddll\fR\& erlang interface can not be removed by using this interface\&. .RE .LP .B char *erl_errno_id(int error) .br .RS .LP This function returns the atom name of the erlang error, given the error number in \fIerror\fR\&\&. Error atoms are: \fIeinval\fR\&, \fIenoent\fR\&, etc\&. It can be used to make error terms from the driver\&. .RE .LP .B void erl_drv_busy_msgq_limits(ErlDrvPort port, ErlDrvSizeT *low, ErlDrvSizeT *high) .br .RS .LP Sets and gets limits that will be used for controling the busy state of the port message queue\&. .LP The port message queue will be set into a busy state when the amount of command data queued on the message queue reaches the \fIhigh\fR\& 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 \fIlow\fR\& limit\&. Command data is in this context data passed to the port using either \fIPort ! {Owner, {command, Data}}\fR\&, or \fIport_command/[2,3]\fR\&\&. Note that these limits only concerns command data that have not yet reached the port\&. The \fBbusy port\fR\& feature can be used for data that has reached the port\&. .LP Valid limits are values in the range \fI[ERL_DRV_BUSY_MSGQ_LIM_MIN, ERL_DRV_BUSY_MSGQ_LIM_MAX]\fR\&\&. 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\&. .LP By passing a pointer to an integer variable containing the value \fIERL_DRV_BUSY_MSGQ_READ_ONLY\fR\&, 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\&. .LP The busy message queue feature can be disabled either by setting the \fIERL_DRV_FLAG_NO_BUSY_MSGQ\fR\& \fBdriver flag\fR\& in the \fBdriver_entry\fR\& used by the driver, or by calling this function with \fIERL_DRV_BUSY_MSGQ_DISABLED\fR\& 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 \fIERL_DRV_BUSY_MSGQ_DISABLED\fR\&, if this feature has been disabled\&. .LP 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\&. .LP For information about busy port functionality see the documentation of the \fBset_busy_port()\fR\& function\&. .RE .LP .B void set_busy_port(ErlDrvPort port, int on) .br .RS .LP This function set and unset the busy state of the port\&. If \fIon\fR\& 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 \fBbusy port message queue\fR\& functionality\&. .LP 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 \fIPort ! {Owner, {command, Data}}\fR\&, or \fIport_command/[2,3]\fR\&\&. .LP If the \fBERL_DRV_FLAG_SOFT_BUSY\fR\& has been set in the \fBdriver_entry\fR\&, data can be forced into the driver via \fBport_command(Port, Data, [force])\fR\& even though the driver has signaled that it is busy\&. .LP For information about busy port message queue functionality see the documentation of the \fBerl_drv_busy_msgq_limits()\fR\& function\&. .RE .LP .B void set_port_control_flags(ErlDrvPort port, int flags) .br .RS .LP This function sets flags for how the \fBcontrol\fR\& driver entry function will return data to the port owner process\&. (The \fIcontrol\fR\& function is called from \fIport_control/3\fR\& in erlang\&.) .LP Currently there are only two meaningful values for \fIflags\fR\&: 0 means that data is returned in a list, and \fIPORT_CONTROL_FLAG_BINARY\fR\& means data is returned as a binary from \fIcontrol\fR\&\&. .RE .LP .B int driver_failure_eof(ErlDrvPort port) .br .RS .LP This function signals to erlang that the driver has encountered an EOF and should be closed, unless the port was opened with the \fIeof\fR\& option, in that case eof is sent to the port\&. Otherwise, the port is closed and an \fI\&'EXIT\&'\fR\& message is sent to the port owner process\&. .LP The return value is 0\&. .RE .LP .B int driver_failure_atom(ErlDrvPort port, char *string) .br .B int driver_failure_posix(ErlDrvPort port, int error) .br .B int driver_failure(ErlDrvPort port, int error) .br .RS .LP These functions signal to Erlang that the driver has encountered an error and should be closed\&. The port is closed and the tuple \fI{\&'EXIT\&', error, Err}\fR\&, is sent to the port owner process, where error is an error atom (\fIdriver_failure_atom\fR\& and \fIdriver_failure_posix\fR\&), or an integer (\fIdriver_failure\fR\&)\&. .LP 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 \fIdriver_output\fR\&\&. .LP The return value is 0\&. .RE .LP .B ErlDrvTermData driver_connected(ErlDrvPort port) .br .RS .LP This function returns the port owner process\&. .LP Note that this function is \fInot\fR\& thread-safe, not even when the emulator with SMP support is used\&. .RE .LP .B ErlDrvTermData driver_caller(ErlDrvPort port) .br .RS .LP This function returns the process id of the process that made the current call to the driver\&. The process id can be used with \fIdriver_send_term\fR\& to send back data to the caller\&. \fIdriver_caller()\fR\& only returns valid data when currently executing in one of the following driver callbacks: .RS 2 .TP 2 .B \fBstart\fR\&: Called from \fIopen_port/2\fR\&\&. .TP 2 .B \fBoutput\fR\&: Called from \fIerlang:send/2\fR\&, and \fIerlang:port_command/2\fR\& .TP 2 .B \fBoutputv\fR\&: Called from \fIerlang:send/2\fR\&, and \fIerlang:port_command/2\fR\& .TP 2 .B \fBcontrol\fR\&: Called from \fIerlang:port_control/3\fR\& .TP 2 .B \fBcall\fR\&: Called from \fIerlang:port_call/3\fR\& .RE .LP Note that this function is \fInot\fR\& thread-safe, not even when the emulator with SMP support is used\&. .RE .LP .B int erl_drv_output_term(ErlDrvTermData port, ErlDrvTermData* term, int n) .br .RS .LP 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 \fBerl_drv_send_term()\fR\& functions can be used for sending to any arbitrary process on the local node\&. .LP .RS -4 .B Note: .RE Note that the \fIport\fR\& parameter is \fInot\fR\& an ordinary port handle, but a port handle converted using \fIdriver_mk_port()\fR\&\&. .LP The \fIterm\fR\& parameter points to an array of \fIErlDrvTermData\fR\&, with \fIn\fR\& 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 \fIport\fR\& parameter specifies the sending port\&. .LP Tuple 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\&. .LP A tuple must be specified with the number of elements\&. (The elements precede the \fIERL_DRV_TUPLE\fR\& term\&.) .LP A list must be specified with the number of elements, including the tail, which is the last term preceding \fIERL_DRV_LIST\fR\&\&. .LP The special term \fIERL_DRV_STRING_CONS\fR\& 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\&. .LP .nf 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 .fi .LP The unsigned integer data type \fIErlDrvUInt\fR\& and the signed integer data type \fIErlDrvSInt\fR\& 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 \fIint\fR\& arguments in the list above\&. .LP The unsigned integer data type \fIErlDrvUInt64\fR\& and the signed integer data type \fIErlDrvSInt64\fR\& are always 64 bits wide\&. They were introduced in erts version 5\&.7\&.4\&. .LP To build the tuple \fI{tcp, Port, [100 | Binary]}\fR\&, the following call could be made\&. .LP .nf ErlDrvBinary* bin = ... ErlDrvPort port = ... ErlDrvTermData spec[] = { ERL_DRV_ATOM, driver_mk_atom("tcp"), ERL_DRV_PORT, driver_mk_port(drvport), ERL_DRV_INT, 100, ERL_DRV_BINARY, bin, 50, 0, ERL_DRV_LIST, 2, ERL_DRV_TUPLE, 3, }; erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); .fi .LP Where \fIbin\fR\& is a driver binary of length at least 50 and \fIdrvport\fR\& is a port handle\&. Note that the \fIERL_DRV_LIST\fR\& comes after the elements of the list, likewise the \fIERL_DRV_TUPLE\fR\&\&. .LP The term \fIERL_DRV_STRING_CONS\fR\& is a way to construct strings\&. It works differently from how \fIERL_DRV_STRING\fR\& works\&. \fIERL_DRV_STRING_CONS\fR\& builds a string list in reverse order, (as opposed to how \fIERL_DRV_LIST\fR\& works), concatenating the strings added to a list\&. The tail must be given before \fIERL_DRV_STRING_CONS\fR\&\&. .LP The \fIERL_DRV_STRING\fR\& constructs a string, and ends it\&. (So it\&'s the same as \fIERL_DRV_NIL\fR\& followed by \fIERL_DRV_STRING_CONS\fR\&\&.) .LP .nf /* 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])); .fi .LP .LP .nf /* 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])); .fi .LP The \fIERL_DRV_EXT2TERM\fR\& term type is used for passing a term encoded with the \fBexternal format\fR\&, i\&.e\&., a term that has been encoded by \fBerlang:term_to_binary\fR\&, \fBerl_interface\fR\&, etc\&. For example, if \fIbinp\fR\& is a pointer to an \fIErlDrvBinary\fR\& that contains the term \fI{17, 4711}\fR\& encoded with the \fBexternal format\fR\& and you want to wrap it in a two tuple with the tag \fImy_tag\fR\&, i\&.e\&., \fI{my_tag, {17, 4711}}\fR\&, you can do as follows: .LP .nf ErlDrvTermData spec[] = { ERL_DRV_ATOM, driver_mk_atom("my_tag"), ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size ERL_DRV_TUPLE, 2, }; erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); .fi .LP If you want to pass a binary and don\&'t already have the content of the binary in an \fIErlDrvBinary\fR\&, you can benefit from using \fIERL_DRV_BUF2BINARY\fR\& instead of creating an \fIErlDrvBinary\fR\& via \fIdriver_alloc_binary()\fR\& and then pass the binary via \fIERL_DRV_BINARY\fR\&\&. The runtime system will often allocate binaries smarter if \fIERL_DRV_BUF2BINARY\fR\& is used\&. However, if the content of the binary to pass already resides in an \fIErlDrvBinary\fR\&, it is normally better to pass the binary using \fIERL_DRV_BINARY\fR\& and the \fIErlDrvBinary\fR\& in question\&. .LP The \fIERL_DRV_UINT\fR\&, \fIERL_DRV_BUF2BINARY\fR\&, and \fIERL_DRV_EXT2TERM\fR\& term types were introduced in the 5\&.6 version of erts\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .RE .LP .B int driver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n) .br .RS .LP .RS -4 .B Warning: .RE \fIdriver_output_term()\fR\& is deprecated and will be removed in the OTP-R17 release\&. Use \fBerl_drv_output_term()\fR\& instead\&. .LP The parameters \fIterm\fR\& and \fIn\fR\& do the same thing as in \fBerl_drv_output_term()\fR\&\&. .LP Note that this function is \fInot\fR\& thread-safe, not even when the emulator with SMP support is used\&. .RE .LP .B ErlDrvTermData driver_mk_atom(char* string) .br .RS .LP This function returns an atom given a name \fIstring\fR\&\&. 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\&. .LP Note that this function is \fInot\fR\& thread-safe, not even when the emulator with SMP support is used\&. .RE .LP .B ErlDrvTermData driver_mk_port(ErlDrvPort port) .br .RS .LP This function converts a port handle to the erlang term format, usable in the \fBerl_drv_output_term()\fR\&, and \fBerl_drv_send_term()\fR\& functions\&. .LP Note that this function is \fInot\fR\& thread-safe, not even when the emulator with SMP support is used\&. .RE .LP .B int erl_drv_send_term(ErlDrvTermData port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) .br .RS .LP This function is the only way for a driver to send data to \fIother\fR\& processes than the port owner process\&. The \fIreceiver\fR\& parameter specifies the process to receive the data\&. .LP .RS -4 .B Note: .RE Note that the \fIport\fR\& parameter is \fInot\fR\& an ordinary port handle, but a port handle converted using \fIdriver_mk_port()\fR\&\&. .LP The parameters \fIport\fR\&, \fIterm\fR\& and \fIn\fR\& do the same thing as in \fBerl_drv_output_term()\fR\&\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .RE .LP .B int driver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n) .br .RS .LP .RS -4 .B Warning: .RE \fIdriver_send_term()\fR\& is deprecated and will be removed in the OTP-R17 release\&. Use \fBerl_drv_send_term()\fR\& instead\&. .LP Also note that parameters of \fIdriver_send_term()\fR\& cannot be properly checked by the runtime system when executed by arbitrary threads\&. This may cause the \fIdriver_send_term()\fR\& function not to fail when it should\&. .LP The parameters \fIterm\fR\& and \fIn\fR\& do the same thing as in \fBerl_drv_output_term()\fR\&\&. .LP This function is only thread-safe when the emulator with SMP support is used\&. .RE .LP .B long driver_async (ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*)) .br .RS .LP This function performs an asynchronous call\&. The function \fIasync_invoke\fR\& is invoked in a thread separate from the emulator thread\&. This enables the driver to perform time-consuming, blocking operations without blocking the emulator\&. .LP The async thread pool size can be set with the \fB+A\fR\& command line argument of \fBerl(1)\fR\&\&. If no async thread pool is available, the call is made synchronously in the thread calling \fIdriver_async()\fR\&\&. The current number of async threads in the async thread pool can be retrieved via \fBdriver_system_info()\fR\&\&. .LP If there is a thread pool available, a thread will be used\&. If the \fIkey\fR\& argument is null, the threads from the pool are used in a round-robin way, each call to \fIdriver_async\fR\& uses the next thread in the pool\&. With the \fIkey\fR\& argument set, this behaviour is changed\&. The two same values of \fI*key\fR\& always get the same thread\&. .LP To make sure that a driver instance always uses the same thread, the following call can be used: .LP .LP .nf unsigned int myKey = driver_async_port_key(myPort); r = driver_async(myPort, &myKey, myData, myFunc); .fi .LP It is enough to initialize \fImyKey\fR\& once for each driver instance\&. .LP 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\&. .LP The \fIasync_data\fR\& is the argument to the functions \fIasync_invoke\fR\& and \fIasync_free\fR\&\&. 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 \fIasync_free\fR\&, because it\&'s called if \fIdriver_async_cancel\fR\& is called\&. .LP When the async operation is done, \fBready_async\fR\& driver entry function is called\&. If \fIready_async\fR\& is null in the driver entry, the \fIasync_free\fR\& function is called instead\&. .LP The return value is a handle to the asynchronous task, which can be used as argument to \fIdriver_async_cancel\fR\&\&. .LP .RS -4 .B Note: .RE 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 \fB+a\fR\& command line argument of \fBerl(1)\fR\&\&. .RE .LP .B unsigned int driver_async_port_key (ErlDrvPort port) .br .RS .LP This function calculates a key for later use in \fBdriver_async()\fR\&\&. The keys are evenly distributed so that a fair mapping between port id\&'s and async thread id\&'s is achieved\&. .LP .RS -4 .B Note: .RE 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\&. .RE .LP .B int driver_async_cancel(long id) .br .RS .LP This function used to cancel a scheduled asynchronous operation, if it was still in the queue\&. It returned 1 if it succeeded, and 0 if it failed\&. .LP Since it could not guarantee success, it was more or less useless\&. The user had to implement synchronization of cancellation anyway\&. It also unnecessarily complicated the implementation\&. Therefore, as of OTP-R15B \fIdriver_async_cancel()\fR\& is deprecated, and scheduled for removal in OTP-R17\&. It will currently always fail, and return 0\&. .LP .RS -4 .B Warning: .RE \fIdriver_async_cancel()\fR\& is deprecated and will be removed in the OTP-R17 release\&. .RE .LP .B int driver_lock_driver(ErlDrvPort port) .br .RS .LP This function locks the driver used by the port \fIport\fR\& 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\&. .RE .LP .B ErlDrvPort driver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data) .br .RS .LP This function creates a new port executing the same driver code as the port creating the new port\&. A short description of the arguments: .RS 2 .TP 2 .B \fIport\fR\&: The port handle of the port (driver instance) creating the new port\&. .TP 2 .B \fIowner_pid\fR\&: 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 \fIdriver_caller(port)\fR\& as \fIowner_pid\fR\&\&. .TP 2 .B \fIname\fR\&: The port name of the new port\&. You usually want to use the same port name as the driver name (\fBdriver_name\fR\& field of the \fBdriver_entry\fR\&)\&. .TP 2 .B \fIdrv_data\fR\&: The driver defined handle that will be passed in subsequent calls to driver call-backs\&. Note, that the \fBdriver start call-back\fR\& will not be called for this new driver instance\&. The driver defined handle is normally created in the \fBdriver start call-back\fR\& when a port is created via \fBerlang:open_port/2\fR\&\&. .RE .LP The caller of \fIdriver_create_port()\fR\& is allowed to manipulate the newly created port when \fIdriver_create_port()\fR\& has returned\&. When \fBport level locking\fR\& 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\&. .LP .RS -4 .B Note: .RE When \fBport level locking\fR\& is used, the creating port is only allowed to manipulate the newly created port until the current driver call-back returns\&. .RE .LP .B int erl_drv_thread_create(char *name, ErlDrvTid *tid, void * (*func)(void *), void *arg, ErlDrvThreadOpts *opts) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIname\fR\&: A string identifying the created thread\&. It will be used to identify the thread in planned future debug functionality\&. .TP 2 .B \fItid\fR\&: A pointer to a thread identifier variable\&. .TP 2 .B \fIfunc\fR\&: A pointer to a function to execute in the created thread\&. .TP 2 .B \fIarg\fR\&: A pointer to argument to the \fIfunc\fR\& function\&. .TP 2 .B \fIopts\fR\&: A pointer to thread options to use or \fINULL\fR\&\&. .RE .LP This function creates a new thread\&. On success \fI0\fR\& is returned; otherwise, an \fIerrno\fR\& value is returned to indicate the error\&. The newly created thread will begin executing in the function pointed to by \fIfunc\fR\&, and \fIfunc\fR\& will be passed \fIarg\fR\& as argument\&. When \fIerl_drv_thread_create()\fR\& returns the thread identifier of the newly created thread will be available in \fI*tid\fR\&\&. \fIopts\fR\& can be either a \fINULL\fR\& pointer, or a pointer to an \fBErlDrvThreadOpts\fR\& structure\&. If \fIopts\fR\& is a \fINULL\fR\& pointer, default options will be used; otherwise, the passed options will be used\&. .LP .RS -4 .B Warning: .RE You are not allowed to allocate the \fBErlDrvThreadOpts\fR\& structure by yourself\&. It has to be allocated and initialized by \fBerl_drv_thread_opts_create()\fR\&\&. .LP The created thread will terminate either when \fIfunc\fR\& returns or if \fBerl_drv_thread_exit()\fR\& is called by the thread\&. The exit value of the thread is either returned from \fIfunc\fR\& or passed as argument to \fBerl_drv_thread_exit()\fR\&\&. The driver creating the thread has the responsibility of joining the thread, via \fBerl_drv_thread_join()\fR\&, before the driver is unloaded\&. It is not possible to create "detached" threads, i\&.e\&., threads that don\&'t need to be joined\&. .LP .RS -4 .B Warning: .RE 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\&. .LP This function is thread-safe\&. .RE .LP .B ErlDrvThreadOpts *erl_drv_thread_opts_create(char *name) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIname\fR\&: A string identifying the created thread options\&. It will be used to identify the thread options in planned future debug functionality\&. .RE .LP This function allocates and initialize a thread option structure\&. On failure \fINULL\fR\& is returned\&. A thread option structure is used for passing options to \fBerl_drv_thread_create()\fR\&\&. If the structure isn\&'t modified before it is passed to \fBerl_drv_thread_create()\fR\&, the default values will be used\&. .LP .RS -4 .B Warning: .RE You are not allowed to allocate the \fBErlDrvThreadOpts\fR\& structure by yourself\&. It has to be allocated and initialized by \fIerl_drv_thread_opts_create()\fR\&\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIopts\fR\&: A pointer to thread options to destroy\&. .RE .LP This function destroys thread options previously created by \fBerl_drv_thread_opts_create()\fR\&\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_thread_exit(void *exit_value) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIexit_value\fR\&: A pointer to an exit value or \fINULL\fR\&\&. .RE .LP This function terminates the calling thread with the exit value passed as argument\&. You are only allowed to terminate threads created with \fBerl_drv_thread_create()\fR\&\&. The exit value can later be retrieved by another thread via \fBerl_drv_thread_join()\fR\&\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_thread_join(ErlDrvTid tid, void **exit_value) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fItid\fR\&: The thread identifier of the thread to join\&. .TP 2 .B \fIexit_value\fR\&: A pointer to a pointer to an exit value, or \fINULL\fR\&\&. .RE .LP This function joins the calling thread with another thread, i\&.e\&., the calling thread is blocked until the thread identified by \fItid\fR\& has terminated\&. On success \fI0\fR\& is returned; otherwise, an \fIerrno\fR\& 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 \fIexit_value == NULL\fR\&, the exit value of the terminated thread will be ignored; otherwise, the exit value of the terminated thread will be stored at \fI*exit_value\fR\&\&. .LP This function is thread-safe\&. .RE .LP .B ErlDrvTid erl_drv_thread_self(void) .br .RS .LP This function returns the thread identifier of the calling thread\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_equal_tids(ErlDrvTid tid1, ErlDrvTid tid2) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fItid1\fR\&: A thread identifier\&. .TP 2 .B \fItid2\fR\&: A thread identifier\&. .RE .LP This function compares two thread identifiers for equality, and returns \fI0\fR\& it they aren\&'t equal, and a value not equal to \fI0\fR\& if they are equal\&. .LP .RS -4 .B Note: .RE 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 \fIerl_drv_equal_tids()\fR\& might not give the expected result\&. .LP This function is thread-safe\&. .RE .LP .B ErlDrvMutex *erl_drv_mutex_create(char *name) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIname\fR\&: A string identifying the created mutex\&. It will be used to identify the mutex in planned future debug functionality\&. .RE .LP This function creates a mutex and returns a pointer to it\&. On failure \fINULL\fR\& is returned\&. The driver creating the mutex has the responsibility of destroying it before the driver is unloaded\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_mutex_destroy(ErlDrvMutex *mtx) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fImtx\fR\&: A pointer to a mutex to destroy\&. .RE .LP This function destroys a mutex previously created by \fBerl_drv_mutex_create()\fR\&\&. The mutex has to be in an unlocked state before being destroyed\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_mutex_lock(ErlDrvMutex *mtx) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fImtx\fR\&: A pointer to a mutex to lock\&. .RE .LP 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 \fInot\fR\& lock the same mutex again\&. .LP .RS -4 .B Warning: .RE If you leave a mutex locked in an emulator thread when you let the thread out of your control, you will \fIvery likely\fR\& deadlock the whole emulator\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_mutex_trylock(ErlDrvMutex *mtx) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fImtx\fR\&: A pointer to a mutex to try to lock\&. .RE .LP This function tries to lock a mutex\&. If successful \fI0\fR\&, is returned; otherwise, \fIEBUSY\fR\& is returned\&. A thread which currently has locked the mutex may \fInot\fR\& try to lock the same mutex again\&. .LP .RS -4 .B Warning: .RE If you leave a mutex locked in an emulator thread when you let the thread out of your control, you will \fIvery likely\fR\& deadlock the whole emulator\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_mutex_unlock(ErlDrvMutex *mtx) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fImtx\fR\&: A pointer to a mutex to unlock\&. .RE .LP This function unlocks a mutex\&. The mutex currently has to be locked by the calling thread\&. .LP This function is thread-safe\&. .RE .LP .B ErlDrvCond *erl_drv_cond_create(char *name) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIname\fR\&: A string identifying the created condition variable\&. It will be used to identify the condition variable in planned future debug functionality\&. .RE .LP This function creates a condition variable and returns a pointer to it\&. On failure \fINULL\fR\& is returned\&. The driver creating the condition variable has the responsibility of destroying it before the driver is unloaded\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_cond_destroy(ErlDrvCond *cnd) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIcnd\fR\&: A pointer to a condition variable to destroy\&. .RE .LP This function destroys a condition variable previously created by \fBerl_drv_cond_create()\fR\&\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_cond_signal(ErlDrvCond *cnd) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIcnd\fR\&: A pointer to a condition variable to signal on\&. .RE .LP This function signals on a condition variable\&. That is, if other threads are waiting on the condition variable being signaled, \fIone\fR\& of them will be woken\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_cond_broadcast(ErlDrvCond *cnd) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIcnd\fR\&: A pointer to a condition variable to broadcast on\&. .RE .LP This function broadcasts on a condition variable\&. That is, if other threads are waiting on the condition variable being broadcast on, \fIall\fR\& of them will be woken\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIcnd\fR\&: A pointer to a condition variable to wait on\&. .TP 2 .B \fImtx\fR\&: A pointer to a mutex to unlock while waiting\&. .TP 2 .B \fI\fR\&: .RE .LP 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\&. .LP .RS -4 .B Note: .RE \fIerl_drv_cond_wait()\fR\& might return even though no-one has signaled or broadcast on the condition variable\&. Code calling \fIerl_drv_cond_wait()\fR\& should always be prepared for \fIerl_drv_cond_wait()\fR\& returning even though the condition that the thread was waiting for hasn\&'t occurred\&. That is, when returning from \fIerl_drv_cond_wait()\fR\& always check if the condition has occurred, and if not call \fIerl_drv_cond_wait()\fR\& again\&. .LP This function is thread-safe\&. .RE .LP .B ErlDrvRWLock *erl_drv_rwlock_create(char *name) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIname\fR\&: A string identifying the created rwlock\&. It will be used to identify the rwlock in planned future debug functionality\&. .RE .LP This function creates an rwlock and returns a pointer to it\&. On failure \fINULL\fR\& is returned\&. The driver creating the rwlock has the responsibility of destroying it before the driver is unloaded\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_rwlock_destroy(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an rwlock to destroy\&. .RE .LP This function destroys an rwlock previously created by \fBerl_drv_rwlock_create()\fR\&\&. The rwlock has to be in an unlocked state before being destroyed\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_rwlock_rlock(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an rwlock to read lock\&. .RE .LP 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 \fInot\fR\& lock the same rwlock again\&. .LP .RS -4 .B Warning: .RE If you leave an rwlock locked in an emulator thread when you let the thread out of your control, you will \fIvery likely\fR\& deadlock the whole emulator\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an rwlock to try to read lock\&. .RE .LP This function tries to read lock an rwlock\&. If successful \fI0\fR\&, is returned; otherwise, \fIEBUSY\fR\& is returned\&. A thread which currently has read or read/write locked the rwlock may \fInot\fR\& try to lock the same rwlock again\&. .LP .RS -4 .B Warning: .RE If you leave an rwlock locked in an emulator thread when you let the thread out of your control, you will \fIvery likely\fR\& deadlock the whole emulator\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_rwlock_runlock(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an rwlock to read unlock\&. .RE .LP This function read unlocks an rwlock\&. The rwlock currently has to be read locked by the calling thread\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_rwlock_rwlock(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an rwlock to read/write lock\&. .RE .LP 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 \fInot\fR\& lock the same rwlock again\&. .LP .RS -4 .B Warning: .RE If you leave an rwlock locked in an emulator thread when you let the thread out of your control, you will \fIvery likely\fR\& deadlock the whole emulator\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an rwlock to try to read/write lock\&. .RE .LP This function tries to read/write lock an rwlock\&. If successful \fI0\fR\&, is returned; otherwise, \fIEBUSY\fR\& is returned\&. A thread which currently has read or read/write locked the rwlock may \fInot\fR\& try to lock the same rwlock again\&. .LP .RS -4 .B Warning: .RE If you leave an rwlock locked in an emulator thread when you let the thread out of your control, you will \fIvery likely\fR\& deadlock the whole emulator\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_rwlock_rwunlock(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an rwlock to read/write unlock\&. .RE .LP This function read/write unlocks an rwlock\&. The rwlock currently has to be read/write locked by the calling thread\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIname\fR\&: A string identifying the created key\&. It will be used to identify the key in planned future debug functionality\&. .TP 2 .B \fIkey\fR\&: A pointer to a thread specific data key variable\&. .RE .LP This function creates a thread specific data key\&. On success \fI0\fR\& is returned; otherwise, an \fIerrno\fR\& value is returned to indicate the error\&. The driver creating the key has the responsibility of destroying it before the driver is unloaded\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_tsd_key_destroy(ErlDrvTSDKey key) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIkey\fR\&: A thread specific data key to destroy\&. .RE .LP This function destroys a thread specific data key previously created by \fBerl_drv_tsd_key_create()\fR\&\&. All thread specific data using this key in all threads have to be cleared (see \fBerl_drv_tsd_set()\fR\&) prior to the call to \fIerl_drv_tsd_key_destroy()\fR\&\&. .LP .RS -4 .B Warning: .RE 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 \fIvery likely\fR\& get unexpected errors in other parts of the system\&. .LP This function is thread-safe\&. .RE .LP .B void erl_drv_tsd_set(ErlDrvTSDKey key, void *data) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIkey\fR\&: A thread specific data key\&. .TP 2 .B \fIdata\fR\&: A pointer to data to associate with \fIkey\fR\& in calling thread\&. .RE .LP This function sets thread specific data associated with \fIkey\fR\& 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 \fINULL\fR\&, before returning from the driver call-back function\&. .LP .RS -4 .B Warning: .RE 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\&. .LP This function is thread-safe\&. .RE .LP .B void *erl_drv_tsd_get(ErlDrvTSDKey key) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIkey\fR\&: A thread specific data key\&. .RE .LP This function returns the thread specific data associated with \fIkey\fR\& for the calling thread\&. If no data has been associated with \fIkey\fR\& for the calling thread, \fINULL\fR\& is returned\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_putenv(char *key, char *value) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIkey\fR\&: A null terminated string containing the name of the environment variable\&. .TP 2 .B \fIvalue\fR\&: A null terminated string containing the new value of the environment variable\&. .RE .LP This function sets the value of an environment variable\&. It returns \fI0\fR\& on success, and a value \fI!= 0\fR\& on failure\&. .LP .RS -4 .B Note: .RE 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\&. .LP .RS -4 .B Warning: .RE Do \fInot\fR\& use libc\&'s \fIputenv\fR\& or similar C library interfaces from a driver\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_getenv(char *key, char *value, size_t *value_size) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIkey\fR\&: A null terminated string containing the name of the environment variable\&. .TP 2 .B \fIvalue\fR\&: A pointer to an output buffer\&. .TP 2 .B \fIvalue_size\fR\&: A pointer to an integer\&. The integer is both used for passing input and output sizes (see below)\&. .RE .LP This function retrieves the value of an environment variable\&. When called, \fI*value_size\fR\& should contain the size of the \fIvalue\fR\& buffer\&. On success \fI0\fR\& is returned, the value of the environment variable has been written to the \fIvalue\fR\& buffer, and \fI*value_size\fR\& contains the string length (excluding the terminating null character) of the value written to the \fIvalue\fR\& buffer\&. On failure, i\&.e\&., no such environment variable was found, a value less than \fI0\fR\& is returned\&. When the size of the \fIvalue\fR\& buffer is too small, a value greater than \fI0\fR\& is returned and \fI*value_size\fR\& has been set to the buffer size needed\&. .LP .RS -4 .B Warning: .RE Do \fInot\fR\& use libc\&'s \fIgetenv\fR\& or similar C library interfaces from a driver\&. .LP This function is thread-safe\&. .RE .LP .B int erl_drv_consume_timeslice(ErlDrvPort port, int percent) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIport\fR\&: Port handle of the executing port\&. .TP 2 .B \fIpercent\fR\&: Approximate consumed fraction of a full time-slice in percent\&. .RE .LP 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 \fI[1, 100]\fR\&\&. The scheduling time-slice is not an exact entity, but can usually be approximated to about 1 millisecond\&. .LP 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 \fIerl_drv_consume_timeslice()\fR\& function in order to determine if it is allowed to continue execution or not\&. .LP \fIerl_drv_consume_timeslice()\fR\& 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\&. .LP 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 \fBwarning\fR\& text at the beginning of this document\&. .RE .LP .B char *erl_drv_cond_name(ErlDrvCond *cnd) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIcnd\fR\&: A pointer to an initialized condition\&. .RE .LP Returns a pointer to the name of the condition\&. .LP .RS -4 .B Note: .RE This function is intended for debugging purposes only\&. .RE .LP .B char *erl_drv_mutex_name(ErlDrvMutex *mtx) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fImtx\fR\&: A pointer to an initialized mutex\&. .RE .LP Returns a pointer to the name of the mutex\&. .LP .RS -4 .B Note: .RE This function is intended for debugging purposes only\&. .RE .LP .B char *erl_drv_rwlock_name(ErlDrvRWLock *rwlck) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fIrwlck\fR\&: A pointer to an initialized r/w-lock\&. .RE .LP Returns a pointer to the name of the r/w-lock\&. .LP .RS -4 .B Note: .RE This function is intended for debugging purposes only\&. .RE .LP .B char *erl_drv_thread_name(ErlDrvTid tid) .br .RS .LP Arguments: .RS 2 .TP 2 .B \fItid\fR\&: A thread identifier\&. .RE .LP Returns a pointer to the name of the thread\&. .LP .RS -4 .B Note: .RE This function is intended for debugging purposes only\&. .RE .SH "SEE ALSO" .LP \fBdriver_entry(3)\fR\&, \fBerl_ddll(3)\fR\&, \fBerlang(3)\fR\& .LP An Alternative Distribution Driver (ERTS User\&'s Guide Ch\&. 3)