From 7e789df8dd9c7d86e9cc354521a37aa598aa5ec8 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Wed, 31 Oct 2012 23:31:50 +0100 Subject: Improve configuration of process and port tables --- erts/doc/src/erl.xml | 67 ++++++++++++++++++++++++++++++++++++------------- erts/doc/src/erlang.xml | 35 +++++++++++++++++++------- 2 files changed, 75 insertions(+), 27 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 4ef3e089a6..f7d8d37fd3 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -586,13 +586,51 @@ erts_alloc(3) for further information.

+ + +

Enable synchronous message passing to ports.

+

As of OTP-R16 message passing to ports are truly asynchronously + implemented. Correctly written Erlang programs should be able + to handle this without any issues. Bugs in existing Erlang + programs that make false assumptions about message passing to + ports may, however, be tricky to find. This switch has been + introduced in order to at least make it easier to compare + behaviors during a transition period. Note that this flag is + deprecated as of its introduction, and is scheduled for removal + in OTP-R17.

+ -

Sets the maximum number of concurrent processes for this - system. must be in the range 16..134217727. - Default is 32768.

-

NOTE: It is possible to choose any value in the range - but powers of 2 perform best.

+

Sets the maximum number of simultaneously existing processes for this + system. Valid range for Number is [1024-134217727]

+

NOTE: The actual maximum chosen may be much larger than + the Number passed. Currently the runtime system often, + but not always, chooses a value that is a power of 2. This might, + however, be changed in the future. The actual value chosen can be + checked by calling + erlang:system_info(process_limit).

+

The default value is 262144

+ + + +

Sets the maximum number of simultaneously existing ports for this + system. Valid range for Number is [1024-134217727]

+

NOTE: The actual maximum chosen may be much larger than + the actual Number passed. Currently the runtime system often, + but not always, chooses a value that is a power of 2. This might, + however, be changed in the future. The actual value chosen can be + checked by calling + erlang:system_info(port_limit).

+

The default value used is normally 65536. However, if + the runtime system is able to determine maximum amount of file + descriptors that it is allowed to open and this value is larger + than 65536, the chosen value will increased to a value + larger or equal to the maximum amount of file descriptors that + can be opened.

+

Previously the environment variable ERL_MAX_PORTS was used + for setting the maximum number of simultaneously existing ports. This + environment variable is deprecated, and scheduled for removal in + OTP-R17, but can still be used.

 @@ -601,21 +639,14 @@ default. This flags sets the emulator in compatibility mode with an earlier Erlang/OTP release . The release number must be in the range - ]]>. This limits the emulator, - making it possible for it to communicate with Erlang nodes - (as well as C- and Java nodes) running that earlier release.

-

For example, an R10 node is not automatically compatible - with an R9 node, but R10 nodes started with the - flag can co-exist with R9 nodes in the same distributed - Erlang system, they are R9-compatible.

+ -2..]]>. This + limits the emulator, making it possible for it to communicate + with Erlang nodes (as well as C- and Java nodes) running that + earlier release.

Note: Make sure all nodes (Erlang-, C-, and Java nodes) of a distributed Erlang system is of the same Erlang/OTP release, or from two different Erlang/OTP releases X and Y, where all Y nodes have compatibility mode X.

-

For example: A distributed Erlang system can consist of - R10 nodes, or of R9 nodes and R9-compatible R10 nodes, but - not of R9 nodes, R9-compatible R10 nodes and "regular" R10 - nodes, as R9 and "regular" R10 nodes are not compatible.

 @@ -1026,7 +1057,7 @@ the given number of seconds have elapsed, the emulator will be terminated by a SIGALRM signal.

 - +

The content of this environment variable will be added to the beginning of the command line for .

@@ -1036,7 +1067,7 @@ the section, i.e. the end of the command line following after an flag.

 - and + and

The content of these environment variables will be added to the end of the command line for .

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 0963904b83..2da456d49f 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -3225,10 +3225,11 @@ os_prompt% the owning process using signals of the form {'EXIT', Port, PosixCode}. See file(3) for possible values of PosixCode.

-

- The maximum number of ports that can be open at the same - time is 1024 by default, but can be configured by - the environment variable ERL_MAX_PORTS.

+

The maximum number of ports that can be open at the same + time can be configured by passing the + +Q + command line flag to + erl(1).

@@ -5954,18 +5955,34 @@ ok

Returns a string containing the OTP release number.

 process_count + +

Returns the number of ports currently existing at + the local node as an integer. The same value as + length(erlang:ports()) returns.

+ + port_limit + +

Returns the maximum number of simultaneously existing + ports at the local node as an integer. This limit + can be configured at startup by using the + +Q + command line flag of + erl(1).

+ + process_count

Returns the number of processes currently existing at the local node as an integer. The same value as length(processes()) returns.

 - process_limit + process_limit -

Returns the maximum number of concurrently existing +

Returns the maximum number of simultaneously existing processes at the local node as an integer. This limit - can be configured at startup by using the command line - flag +P, see - erl(1).

+ can be configured at startup by using the + +P + command line flag of + erl(1).

 procs -- cgit v1.2.3 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') 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 From 6e01408aba71e26884c5db81b8e4fa89bd803576 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Fri, 21 Sep 2012 15:12:07 +0200 Subject: Implement true asynchronous signaling between processes and ports --- erts/doc/src/erl.xml | 60 +++++++++++++++---- erts/doc/src/erlang.xml | 152 +++++++++++++++++++++++++++++++++++------------- 2 files changed, 158 insertions(+), 54 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index f7d8d37fd3..85c6140b01 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -586,18 +586,38 @@ erts_alloc(3) for further information.

- - -

Enable synchronous message passing to ports.

-

As of OTP-R16 message passing to ports are truly asynchronously - implemented. Correctly written Erlang programs should be able - to handle this without any issues. Bugs in existing Erlang - programs that make false assumptions about message passing to - ports may, however, be tricky to find. This switch has been - introduced in order to at least make it easier to compare - behaviors during a transition period. Note that this flag is - deprecated as of its introduction, and is scheduled for removal - in OTP-R17.

+ + +

Control behavior of signals to ports.

+

As of OTP-R16 signals to ports are truly asynchronously + delivered. Note that signals always have been documented as + asynchronous. The underlying implementation has, however, + previously delivered these signals synchronously. Correctly + written Erlang programs should be able to handle this without + any issues. Bugs in existing Erlang programs that make false + assumptions about signals to ports may, however, be tricky to + find. This switch has been introduced in order to at least + make it easier to compare behaviors during a transition period. + Note that this flag is deprecated as of its + introduction, and is scheduled for removal in OTP-R17. + Behavior should be one of the following characters:

+ + d + The default. Asynchronous signals. A process that sends + a signal to a port may continue execution before the signal + has been delivered to the port. + s + Synchronous signals. A processes that sends a signal + to a port will not continue execution until the signal has + been delivered. Should only be used for testing and + debugging. + a + Asynchronous signals. As the default, but a processes + that sends a signal will even more frequently continue + execution before the signal has been delivered to the + port. Should only be used for testing and + debugging. + @@ -948,6 +968,22 @@ without prior notice.

+ +spp Bool + +

Set default scheduler hint for port parallelism. If set to + true, the VM will schedule port tasks when it by this can + improve the parallelism in the system. If set to false, + the VM will try to perform port tasks immediately and by this + improve latency at the expense of parallelism. If this + flag has not been passed, the default scheduler hint for port + parallelism is currently false. The default used can be + inspected in runtime by calling + erlang:system_info(port_parallelism). + The default can be overriden on port creation by passing the + parallelism + option to + open_port/2

. +

Suggested stack size, in kilowords, for scheduler threads. diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 2da456d49f..57346d3935 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -1000,14 +1000,14 @@ b exit(Pid, Reason) -> true - Send an exit signal to a process + Send an exit signal to a process or port - Pid = pid() + Pid = pid() | port() Reason = term()

Sends an exit signal with exit reason Reason to - the process Pid.

+ the process or port identified by Pid.

The following behavior apply if Reason is any term except normal or kill:

If Pid is not trapping exits, Pid itself will @@ -2875,7 +2875,7 @@ os_prompt%  FileNameChar = integer() (1..255 or any Unicode codepoint, see description)  In = Out = integer() PortSettings = [Opt] -  Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ ArgString ]} | {arg0, ArgString} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof +  Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ ArgString ]} | {arg0, ArgString} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof | {parallelism, true|false}   N = 1 | 2 | 4   L = integer()   Dir = string() @@ -3173,6 +3173,18 @@ os_prompt% console window when spawning the port program. (This option has no effect on other platforms.)

 + {parallelism, Boolean} + +

Set scheduler hint for port parallelism. If set to true, + the VM will schedule port tasks when it by this can improve the + parallelism in the system. If set to false, the VM will + try to perform port tasks immediately and by this improving the + latency at the expense of parallelism. The default can be set on + system startup by passing the + +spp command line argument + to erl(1). +

+

The default is stream for all types of port and use_stdio for spawned ports.

@@ -3299,10 +3311,10 @@ os_prompt%

Closes an open port. Roughly the same as Port ! {self(), close} except for the error behaviour - (see below), and that the port does not reply with - {Port, closed}. Any process may close a port with - port_close/1, not only the port owner (the connected - process).

+ (see below), being synchronous, and that the port does + not reply with {Port, closed}. Any process may + close a port with port_close/1, not only the port owner + (the connected process).

For comparison: Port ! {self(), close} fails with badarg if Port cannot be sent to (i.e., Port refers neither to a port nor to a process). If @@ -3314,8 +3326,12 @@ os_prompt%

Note that any process can close a port using Port ! {PortOwner, close} just as if it itself was the port owner, but the reply always goes to the port owner.

-

In short: port_close(Port) has a cleaner and more - logical behaviour than Port ! {self(), close}.

+

As of OTP-R16 Port ! {PortOwner, close} is truly + asynchronous. Note that this operation has always been + documented as an asynchronous operation, while the underlying + implementation has been synchronous. port_close/1 is + however still fully synchronous. This due to its error + behavior.

Failure: badarg if Port is not an open port or the registered name of an open port.

 @@ -3329,11 +3345,11 @@ os_prompt%

Sends data to a port. Same as - Port ! {self(), {command, Data}} except for the error - behaviour (see below). Any process may send data to a port - with port_command/2, not only the port owner - (the connected process).

-

For comparison: Port ! {self(), {command, Data}} + Port ! {PortOwner, {command, Data}} except for the error + behaviour and being synchronous (see below). Any process may + send data to a port with port_command/2, not only the + port owner (the connected process).

+

For comparison: Port ! {PortOwner, {command, Data}} fails with badarg if Port cannot be sent to (i.e., Port refers neither to a port nor to a process). If Port is a closed port the data message disappears @@ -3344,11 +3360,14 @@ os_prompt%

Note that any process can send to a port using Port ! {PortOwner, {command, Data}} just as if it itself was the port owner.

-

In short: port_command(Port, Data) has a cleaner and - more logical behaviour than - Port ! {self(), {command, Data}}.

If the port is busy, the calling process will be suspended until the port is not busy anymore.

+

As of OTP-R16 Port ! {PortOwner, {command, Data}} is + truly asynchronous. Note that this operation has always been + documented as an asynchronous operation, while the underlying + implementation has been synchronous. port_command/2 is + however still fully synchronous. This due to its error + behavior.

Failures:

badarg @@ -3433,7 +3452,7 @@ os_prompt%

Sets the port owner (the connected port) to Pid. - Roughly the same as Port ! {self(), {connect, Pid}} + Roughly the same as Port ! {Owner, {connect, Pid}} except for the following:

@@ -3443,6 +3462,9 @@ os_prompt%

The port does not reply with {Port,connected}.

 + +

port_connect/1 is synchronous, see below.

+

The new port owner gets linked to the port.

 @@ -3467,9 +3489,12 @@ os_prompt% Port ! {PortOwner, {connect, Pid}} just as if it itself was the port owner, but the reply always goes to the port owner.

-

In short: port_connect(Port, Pid) has a cleaner and - more logical behaviour than - Port ! {self(),{connect,Pid}}.

+

As of OTP-R16 Port ! {PortOwner, {connect, Pid}} is + truly asynchronous. Note that this operation has always been + documented as an asynchronous operation, while the underlying + implementation has been synchronous. port_connect/2 is + however still fully synchronous. This due to its error + behavior.

Failure: badarg if Port is not an open port or the registered name of an open port, or if Pid is not an existing local pid.

@@ -3538,12 +3563,35 @@ os_prompt% the Port, or undefined if the port is not open. The order of the tuples is not defined, nor are all the tuples mandatory.

+

Currently the result will containt information about the + following Items: registered_name (if the port has + a registed name), id, connected, links, + name, input, and output. For more information + about the different Items, see + port_info/2.

+

Failure: badarg if Port is not a local port.

+ + + + erlang:port_info(Port, Item) -> {Item, Info} | undefined | [] + Information about a port + + Port = port() | atom() + Item, Info -- see below + + +

Returns information about Port as specified + by Item, or undefined if the port is not open. + Also, if Item == registered_name and the port has no + registered name, [] is returned.

+

Valid values of Item, and corresponding {Item, Info} + tuples:

{registered_name, RegName}

RegName (an atom) is the registered name of - the port. If the port has no registered name, this tuple - is not present in the list.

+ the port. If the port has no registered name, [] + is returned.

 {id, Index} @@ -3574,28 +3622,43 @@ os_prompt%

Bytes is the total number of bytes written to the port.

 + {monitors, Monitors} + +

Monitors represent processes that this port + is monitoring. Note that the type of Monitors is + likey to change in the future.

+ + {parallelism, Boolean} + +

Boolean corresponds to the port parallelism + hint being used by this port. For more information see + the parallelism + option of open_port/2.

+ + {memory, MemSz} + +

MemSz is the total amount of memory, in bytes, + allocated for this port by the runtime system. Note that + the port itself might have allocated memory which is not + included in MemSz.

+ + {queue_size, QSz} + +

QSz is the total amount of data, in bytes, queued + by the port using the ERTS driver queue implementation.

+ + {locking, Locking} + +

Locking is currently either false (emulator + without SMP support), port_level (port specific locking), + or driver_level (driver specific locking). Note that + these results are highly implementation specific and might + change in the future.

+

Failure: badarg if Port is not a local port.

 - - erlang:port_info(Port, Item) -> {Item, Info} | undefined | [] - Information about a port - - Port = port() | atom() - Item, Info -- see below - - -

Returns information about Port as specified - by Item, or undefined if the port is not open. - Also, if Item == registered_name and the port has no - registered name, [] is returned.

-

For valid values of Item, and corresponding - values of Info, see - erlang:port_info/1.

-

Failure: badarg if Port is not a local port.

- - erlang:port_to_list(Port) -> string() Text representation of a port identifier @@ -5954,6 +6017,11 @@ ok

Returns a string containing the OTP release number.

 + port_parallelism +

Returns the default port parallelism scheduling hint used. + For more information see the + +spp command line argument + of erl(1).

 process_count

Returns the number of ports currently existing at -- cgit v1.2.3 From 9e4895da833b7777e69efc173f5dc777aaea3201 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Thu, 29 Nov 2012 01:24:43 +0100 Subject: Add support for busy port message queue --- erts/doc/src/driver_entry.xml | 16 ++++++--- erts/doc/src/erl_driver.xml | 81 +++++++++++++++++++++++++++++++++++++++---- 2 files changed, 86 insertions(+), 11 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index a2efdf3ebc..d65a38570d 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -377,11 +377,11 @@ typedef struct erl_drv_entry { int driver_flags -

This field is used to pass driver capability information to the - runtime system. If the extended_marker field equals - ERL_DRV_EXTENDED_MARKER, it should contain 0 or - driver flags (ERL_DRV_FLAG_*) ored bitwise. Currently - the following driver flags exist: +

This field is used to pass driver capability and other + information to the runtime system. If the + extended_marker field equals ERL_DRV_EXTENDED_MARKER, + it should contain 0 or driver flags (ERL_DRV_FLAG_*) + ored bitwise. Currently the following driver flags exist:

ERL_DRV_FLAG_USE_PORT_LOCKING @@ -404,6 +404,12 @@ typedef struct erl_drv_entry { by the Erlang distribution (the behaviour has always been required by drivers used by the distribution). + ERL_DRV_FLAG_NO_BUSY_MSGQ + Disable busy port message queue functionality. For + more information, see the documentation of the + erl_drv_busy_msgq_limits() + function. + void *handle2 diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index fcce962557..903b8dfe64 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1499,17 +1499,82 @@ typedef struct ErlIOVec { error terms from the driver.

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

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

+

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

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

This function set and resets the busy status of the port. If - on is 1, the port is set to busy, if it's 0 the port - is set to not busy.

-

When the port is busy, sending to it with Port ! Data - or port_command/2, will block the port owner process, - until the port is signaled as not busy.

+

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

+

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

If the has been set in the @@ -1518,6 +1583,10 @@ typedef struct ErlIOVec { port_command(Port, Data, [force]) even though the driver has signaled that it is busy.

+

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

 -- cgit v1.2.3 From e841f8c34bd82d6d39647e6f0f426f554b62acf1 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Mon, 3 Dec 2012 03:19:43 +0100 Subject: Add documentation on communication in Erlang --- erts/doc/src/Makefile | 1 + erts/doc/src/communication.xml | 89 ++++++++++++++++++++++++++++++++++++++++++ erts/doc/src/part.xml | 1 + 3 files changed, 91 insertions(+) create mode 100644 erts/doc/src/communication.xml (limited to 'erts/doc') diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index cfa5527474..524cd6ae94 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -78,6 +78,7 @@ XML_CHAPTER_FILES = \ inet_cfg.xml \ erl_ext_dist.xml \ erl_dist_protocol.xml \ + communication.xml \ notes.xml \ notes_history.xml diff --git a/erts/doc/src/communication.xml b/erts/doc/src/communication.xml new file mode 100644 index 0000000000..6049123f6a --- /dev/null +++ b/erts/doc/src/communication.xml @@ -0,0 +1,89 @@ + + + + +
+ + 20122012 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Communication in Erlang + Rickard Green + + + + + 2012-12-03 + PA1 + communication.xml +
+

Communication in Erlang is conceptually performed using + asynchronous signaling. All different executing entities + such as processes, and ports communicate via asynchronous + signals. The most commonly used signal is a message. Other + common signals are exit, link, unlink, monitor, demonitor + signals.

+
+ Passing of Signals +

The amount of time that passes between a signal being sent + and the arrival of the signal at the destination is unspecified + but positive. If the receiver has terminated, the signal will + not arrive, but it is possible that it triggers another signal. + For example, a link signal sent to a non-existing process will + trigger an exit signal which will be sent back to where the link + signal originated from. When communicating over the distribution, + signals may be lost if the distribution channel goes down.

+

The only signal ordering guarantee given is the following. If + an entity sends multiple signals to the same destination entity, + the order will be preserved. That is, if A send + a signal S1 to B, and later sends + the signal S2 to B, S1 is guaranteed not to + arrive after S2.

+
+
+ Synchronous Communication +

Some communication is synchronous. If broken down into pieces, + a synchronous communication operation, consists of two asynchronous + signals. One request signal and one reply signal. An example of + such a synchronous communication is a call to process_info/2 + when the first argument is not self(). The caller will send + an asynchronous signal requesting information, and will then + wait for the reply signal containing the requested information. When + the request signal reaches its destination the destination process + replies with the requested information.

+
+
+ Implementation +

The implementation of different asynchronous signals in the + VM may vary over time, but the behavior will always respect this + concept of asynchronous signals being passed between entities + as described above.

+

By inspecting the implementation you might notice that some + specific signal actually gives a stricter guarantee than described + above. It is of vital importance that such knowledge about the + implementation is not used by Erlang code, since the + implementation might change at any time without prior notice.

+

Some example of major implementation changes:

+ + As of ERTS version 5.5.2 exit signals to processes are truly + asynchronously delivered. + As of ERTS version 5.10 all signals from processes to ports + are truly asynchronously delivered. + +
+ + diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml index e27b722721..2c178556d4 100644 --- a/erts/doc/src/part.xml +++ b/erts/doc/src/part.xml @@ -31,6 +31,7 @@

The Erlang Runtime System Application ERTS.

 + -- cgit v1.2.3