From 23c6f9e07a3cae7c05e55abd01ff798384241538 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Sun, 16 Sep 2012 02:45:32 +0200 Subject: Add erl_drv_[send|output]_term --- erts/doc/src/erl_driver.xml | 104 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 84 insertions(+), 20 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 4fd74b783e..fcce962557 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -123,12 +123,20 @@ different threads. This, however, is not a problem for any function in this API, since the emulator has control over these threads.

- -

Functions not explicitly documented as thread-safe are - not thread-safe. Also note that some functions + +

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

- +

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

+

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

+
@@ -1570,6 +1578,8 @@ typedef struct ErlIOVec {

This function returns the port owner process.

+

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

 @@ -1597,22 +1607,32 @@ typedef struct ErlIOVec { call Called from erlang:port_call/3 +

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

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

This functions sends data in the special driver term - format. 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.

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

+

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

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

+ term first has a term type, and then arguments. The + port parameter specifies the sending port.

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 @@ -1664,17 +1684,17 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ErlDrvPort port = ... ErlDrvTermData spec[] = { ERL_DRV_ATOM, driver_mk_atom("tcp"), - ERL_DRV_PORT, driver_mk_port(port), + 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, }; - driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]>

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

The term ERL_DRV_STRING_CONS is a way to construct @@ -1695,7 +1715,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ERL_DRV_NIL, ERL_DRV_LIST, 4 }; - driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]>

The ERL_DRV_EXT2TERM term type is used for passing a term encoded with the @@ -1725,7 +1745,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size ERL_DRV_TUPLE, 2, }; - driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0])); + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]>

If you want to pass a binary and don't already have the content of the binary in an ErlDrvBinary, you can benefit from using @@ -1741,6 +1761,22 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len ERL_DRV_EXT2TERM term types were introduced in the 5.6 version of erts.

+

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

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

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

+ +

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

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

 @@ -1754,6 +1790,8 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len string. The atom is created and won't change, so the return value may be saved and reused, which is faster than looking up the atom several times.

+

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

 @@ -1762,20 +1800,46 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len

This function converts a port handle to the erlang term - format, usable in the driver_output_send function.

+ format, usable in the erl_drv_output_term(), and erl_drv_send_term() functions.

+

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

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

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

+

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

 +

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

+

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

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

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

+

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

+

The parameters term and n do the same thing - as in driver_output_term.

+ as in erl_drv_output_term().

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

 -- cgit v1.2.3