From 3ee5343415d6ae0ce1ff1c2a2555051431a9315e Mon Sep 17 00:00:00 2001 From: Dmytro Lytovchenko Date: Wed, 25 May 2016 14:37:03 +0200 Subject: erts: Add port monitors * erlang:monitor/2 with port argument is added, erlang:demonitor, using port task API and avoiding locking; * port_info and process_info support for monitored ports (with named port monitors support); * Exit signals contain type 'process' or 'port'; * Propagation of port exit signals; * Self-cleaning when origin process dies with monitor on; * 8 test cases + testcase for port driver crashing; * Documentation for all of the above (monitor, demonitor, port_info and process_info) updated --- erts/doc/src/erlang.xml | 239 ++++++++++++++++++++++++++---------------------- 1 file changed, 132 insertions(+), 107 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index e0c3fed0c2..fa13e4c142 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -2916,107 +2916,105 @@ os_prompt% + Starts monitoring. + -

Send a monitor request of type Type to the - entity identified by Item. The caller of - monitor/2 will later be notified by a monitor message on the - following format if the monitored state is changed:

+

Sends a monitor request of type Type to the + entity identified by Item. If the monitored entity + does not exist or when it dies, the caller of monitor/2 will + be notified by a message on the following format:

{Tag, MonitorRef, Type, Object, Info}

The monitor request is an asynchronous signal. That is, it takes time before the signal reaches its destination.

 -

Valid Types:

- - process - -

Monitor the existence of the process identified by - Item. Valid - Items in combination with the - process Type can be any of the following:

- - pid() - -

The process identifier of the process to monitor.

- - {RegisteredName, Node} - -

A tuple consisting of a registered name of a process and - a node name. The process residing on the node Node - with the registered name {RegisteredName, Node} will - be monitored.

- - RegisteredName - -

The process locally registered as RegisteredName - will become monitored.

- - -

When a registered name is used, the - process that has the registered name when the - monitor request reach its destination will be monitored. - The monitor is not effected if the registered name is - unregistered, or unregistered and later registered on another - process.

 -

The monitor is triggered either when the monitored process - terminates, is non existing, or if the connection to it is - lost. In the case the connection to it is lost, we do not know - if it still exist or not. After this type of monitor has been - triggered, the monitor is automatically removed.

-

When the monitor is triggered a 'DOWN' message is - sent to the monitoring process. A 'DOWN' message has - the following pattern:

- {'DOWN', MonitorRef, Type, Object, Info} -

Here MonitorRef and Type are the same as - described earlier, and:

- - Object - -

equals:

- - Item - If Item is specified by a - process identifier. - {RegisteredName, Node} - If Item is specified as - RegisteredName, or {RegisteredName, Node} - where Node corresponds to the node that the - monitored process resides on. - - - Info - -

Either the exit reason of the process, noproc - (non-existing process), or noconnection (no - connection to the node where the monitored process - resides).

 - -

The monitoring is turned off when the 'DOWN' - message is sent or when - demonitor/1 - is called.

-

If an attempt is made to monitor a process on an older node - (where remote process monitoring is not implemented or - where remote process monitoring by registered name is not - implemented), the call fails with badarg.

- -

The format of the 'DOWN' message changed in ERTS - version 5.2 (OTP R9B) for monitoring - by registered name. Element Object of - the 'DOWN' message could in earlier versions - sometimes be the process identifier of the monitored process and sometimes - be the registered name. Now element Object is - always a tuple consisting of the registered name and - the node name. Processes on new nodes (ERTS version 5.2 - or higher) always get 'DOWN' messages on - the new format even if they are monitoring processes on old - nodes. Processes on old nodes always get 'DOWN' - messages on the old format.

- - - time_offset + +

Type can be one of the following atoms: + process, port or time_offset.

+ +

A monitor is triggered only once, after that it is removed from + both monitoring process and the monitored entity. + Monitors are fired when the monitored process or port terminates, + does not exist at the moment of creation, or if the connection to + it is lost. In the case with connection, we lose knowledge about + the fact if it still exists or not. The monitoring is also turned off + when demonitor/1 + is called.

+ +

When monitoring by name please note, that the RegisteredName + is resolved to pid() or port() only once + at the moment of monitor instantiation, later changes to the name + registration will not affect the existing monitor.

+ +

When a monitor is triggered, a 'DOWN' message that has the + following pattern {'DOWN', MonitorRef, Type, Object, Info} + is sent to the monitoring process.

+ +

In monitor message MonitorRef and Type are the same as + described earlier, and:

+ + Object + +

The monitored entity, which triggered the event. When monitoring + a local process or port, Object will be equal to the + pid() or port() that was being monitored. When + monitoring process or port by name, Object will have format + {RegisteredName, Node} where RegisteredName is the + name which has been used with monitor/2 call and + Node is local or remote node name (for ports monitored by + name, Node is always local node name).

+ + Info + +

Either the exit reason of the process, noproc + (process or port did not exist at the time of monitor creation), + or noconnection (no connection to the node where the + monitored process resides).

+ + +

If an attempt is made to monitor a process on an older node + (where remote process monitoring is not implemented or + where remote process monitoring by registered name is not + implemented), the call fails with badarg.

+ +

The format of the 'DOWN' message changed in ERTS + version 5.2 (OTP R9B) for monitoring + by registered name. Element Object of + the 'DOWN' message could in earlier versions + sometimes be the process identifier of the monitored process and sometimes + be the registered name. Now element Object is + always a tuple consisting of the registered name and + the node name. Processes on new nodes (ERTS version 5.2 + or higher) always get 'DOWN' messages on + the new format even if they are monitoring processes on old + nodes. Processes on old nodes always get 'DOWN' + messages on the old format.

+ + + + Monitoring a process + +

Creates monitor between the current process and another + process identified by Item, which can be a + pid() (local or remote), an atom RegisteredName or + a tuple {RegisteredName, Node} for a registered process, + located elsewhere.

+ + + Monitoring a port + +

Creates monitor between the current process and a port + identified by Item, which can be a + port() (only local), an atom RegisteredName or + a tuple {RegisteredName, Node} for a registered port, + located on this node. Note, that attempt to monitor a remote port + will result in badarg.

+ + + Monitoring a + time_offset

Monitor changes in time offset @@ -3072,15 +3070,17 @@ os_prompt% Note that you can observe the change of the time offset when calling erlang:time_offset() before you get the 'CHANGE' message.

- +

Making several calls to monitor/2 for the same - Item and/or Type is not - an error; it results in as many independent monitoring instances.

+ Item and/or Type is not + an error; it results in as many independent monitoring instances.

+

The monitor functionality is expected to be extended. That is, - other Types and Items - are expected to be supported in a future release.

+ other Types and Items + are expected to be supported in a future release.

+

If or when monitor/2 is extended, other possible values for Tag, Object and @@ -4150,6 +4150,22 @@ os_prompt% + Which processes are monitoring this port. + +

Returns list of pids that are monitoring given port at the + moment.

+

If the port identified by Port is not open, + undefined is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + port_info/2 returns undefined.

+

Failure: badarg if Port is not a local + port identifier, or an atom.

+ + + + + Information about the name of a port.

Name is the command name set by @@ -4165,7 +4181,7 @@ os_prompt% - + Information about the OS pid of a port.

OsPid is the process identifier (or equivalent) @@ -4184,7 +4200,7 @@ os_prompt% - + Information about the output of a port.

Bytes is the total number of bytes written @@ -4203,7 +4219,7 @@ os_prompt% - + Information about the parallelism hint of a port.

Boolean corresponds to the port parallelism @@ -4214,7 +4230,7 @@ os_prompt% - + Information about the queue size of a port.

Bytes is the total number @@ -4231,7 +4247,7 @@ os_prompt% - + Information about the registered name of a port.

RegisteredName is the registered name of @@ -4865,10 +4881,19 @@ os_prompt%

A list of monitors (started by monitor/2) that are active for the process. For a local process monitor or a remote process monitor by a process - identifier, the list item is {process, Pid}. - For a remote process - monitor by name, the list item is - {process, {RegName, Node}}.

+ identifier, the list consists of:

+ + {process, Pid} + Process is monitored by pid. + {process, {RegName, Node}} + Local or remote process is monitored by name. + {port, PortId} + Local port is monitored by port id. + {port, {RegName, Node}} + Local port is monitored by name. Please note, that + remote port monitors are not supported, so Node will + always be the local node name. + {message_queue_data, MQD} -- cgit v1.2.3