aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erlang.xml
diff options
context:
space:
mode:
authorLukas Larsson <[email protected]>2016-06-10 09:47:24 +0200
committerLukas Larsson <[email protected]>2016-06-10 09:47:24 +0200
commit7979f72ce15ec5eeb8e0e9cfc1c291f10c4f0432 (patch)
tree582f90aac92b208b3fbf20c2f50bb588e28a6f53 /erts/doc/src/erlang.xml
parent77e69343b8bf6de63242cbcea7ebb35be3bb99e9 (diff)
parent3ee5343415d6ae0ce1ff1c2a2555051431a9315e (diff)
downloadotp-7979f72ce15ec5eeb8e0e9cfc1c291f10c4f0432.tar.gz
otp-7979f72ce15ec5eeb8e0e9cfc1c291f10c4f0432.tar.bz2
otp-7979f72ce15ec5eeb8e0e9cfc1c291f10c4f0432.zip
Merge branch 'kvakvs/erts/monitor_port/OTP-11384'
* kvakvs/erts/monitor_port/OTP-11384: erts: Add port monitors
Diffstat (limited to 'erts/doc/src/erlang.xml')
-rw-r--r--erts/doc/src/erlang.xml239
1 files changed, 132 insertions, 107 deletions
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% </pre>
<func>
<name name="monitor" arity="2" clause_i="1"/>
<name name="monitor" arity="2" clause_i="2"/>
+ <name name="monitor" arity="2" clause_i="3"/>
<fsummary>Starts monitoring.</fsummary>
<type name="registered_name"/>
<type name="registered_process_identifier"/>
<type name="monitor_process_identifier"/>
+ <type name="monitor_port_identifier"/>
<desc>
- <p>Send a monitor request of type <c><anno>Type</anno></c> to the
- entity identified by <c><anno>Item</anno></c>. The caller of
- <c>monitor/2</c> will later be notified by a monitor message on the
- following format if the monitored state is changed:</p>
+ <p>Sends a monitor request of type <c><anno>Type</anno></c> to the
+ entity identified by <c><anno>Item</anno></c>. If the monitored entity
+ does not exist or when it dies, the caller of <c>monitor/2</c> will
+ be notified by a message on the following format:</p>
<code type="none">{Tag, <anno>MonitorRef</anno>, <anno>Type</anno>, Object, Info}</code>
<note><p>The monitor request is an asynchronous signal. That is, it
takes time before the signal reaches its destination.</p></note>
- <p>Valid <c><anno>Type</anno></c>s:</p>
- <taglist>
- <tag><marker id="monitor_process"/><c>process</c></tag>
- <item>
- <p>Monitor the existence of the process identified by
- <c><anno>Item</anno></c>. Valid
- <c><anno>Item</anno></c>s in combination with the
- <c>process <anno>Type</anno></c> can be any of the following:</p>
- <taglist>
- <tag><c>pid()</c></tag>
- <item>
- <p>The process identifier of the process to monitor.</p>
- </item>
- <tag><c>{RegisteredName, Node}</c></tag>
- <item>
- <p>A tuple consisting of a registered name of a process and
- a node name. The process residing on the node <c>Node</c>
- with the registered name <c>{RegisteredName, Node}</c> will
- be monitored.</p>
- </item>
- <tag><c>RegisteredName</c></tag>
- <item>
- <p>The process locally registered as <c>RegisteredName</c>
- will become monitored.</p>
- </item>
- </taglist>
- <note><p>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.</p></note>
- <p>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.</p>
- <p>When the monitor is triggered a <c>'DOWN'</c> message is
- sent to the monitoring process. A <c>'DOWN'</c> message has
- the following pattern:</p>
- <code type="none">{'DOWN', MonitorRef, Type, Object, Info}</code>
- <p>Here <c>MonitorRef</c> and <c>Type</c> are the same as
- described earlier, and:</p>
- <taglist>
- <tag><c>Object</c></tag>
- <item>
- <p>equals:</p>
- <taglist>
- <tag><c><anno>Item</anno></c></tag>
- <item>If <c><anno>Item</anno></c> is specified by a
- process identifier.</item>
- <tag><c>{RegisteredName, Node}</c></tag>
- <item>If <c><anno>Item</anno></c> is specified as
- <c>RegisteredName</c>, or <c>{RegisteredName, Node}</c>
- where <c>Node</c> corresponds to the node that the
- monitored process resides on.</item>
- </taglist>
- </item>
- <tag><c>Info</c></tag>
- <item>
- <p>Either the exit reason of the process, <c>noproc</c>
- (non-existing process), or <c>noconnection</c> (no
- connection to the node where the monitored process
- resides).</p></item>
- </taglist>
- <p>The monitoring is turned off when the <c>'DOWN'</c>
- message is sent or when
- <seealso marker="#demonitor/1">demonitor/1</seealso>
- is called.</p>
- <p>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 <c>badarg</c>.</p>
- <note>
- <p>The format of the <c>'DOWN'</c> message changed in ERTS
- version 5.2 (OTP R9B) for monitoring
- <em>by registered name</em>. Element <c>Object</c> of
- the <c>'DOWN'</c> message could in earlier versions
- sometimes be the process identifier of the monitored process and sometimes
- be the registered name. Now element <c>Object</c> 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 <c>'DOWN'</c> messages on
- the new format even if they are monitoring processes on old
- nodes. Processes on old nodes always get <c>'DOWN'</c>
- messages on the old format.</p>
- </note>
- </item>
- <tag><marker id="monitor_time_offset"/><c>time_offset</c></tag>
+
+ <p><c><anno>Type</anno></c> can be one of the following atoms:
+ <c>process</c>, <c>port</c> or <c>time_offset</c>.</p>
+
+ <p>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 <seealso marker="#demonitor/1">demonitor/1</seealso>
+ is called.</p>
+
+ <p>When monitoring by name please note, that the <c>RegisteredName</c>
+ is resolved to <c>pid()</c> or <c>port()</c> only once
+ at the moment of monitor instantiation, later changes to the name
+ registration will not affect the existing monitor.</p>
+
+ <p>When a monitor is triggered, a <c>'DOWN'</c> message that has the
+ following pattern <c>{'DOWN', MonitorRef, Type, Object, Info}</c>
+ is sent to the monitoring process.</p>
+
+ <p>In monitor message <c>MonitorRef</c> and <c>Type</c> are the same as
+ described earlier, and:</p>
+ <taglist>
+ <tag><c>Object</c></tag>
+ <item>
+ <p>The monitored entity, which triggered the event. When monitoring
+ a local process or port, <c>Object</c> will be equal to the
+ <c>pid()</c> or <c>port()</c> that was being monitored. When
+ monitoring process or port by name, <c>Object</c> will have format
+ <c>{RegisteredName, Node}</c> where <c>RegisteredName</c> is the
+ name which has been used with <c>monitor/2</c> call and
+ <c>Node</c> is local or remote node name (for ports monitored by
+ name, <c>Node</c> is always local node name).</p>
+ </item>
+ <tag><c>Info</c></tag>
+ <item>
+ <p>Either the exit reason of the process, <c>noproc</c>
+ (process or port did not exist at the time of monitor creation),
+ or <c>noconnection</c> (no connection to the node where the
+ monitored process resides). </p></item>
+ </taglist>
+
+ <p>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 <c>badarg</c>.</p>
+ <note>
+ <p>The format of the <c>'DOWN'</c> message changed in ERTS
+ version 5.2 (OTP R9B) for monitoring
+ <em>by registered name</em>. Element <c>Object</c> of
+ the <c>'DOWN'</c> message could in earlier versions
+ sometimes be the process identifier of the monitored process and sometimes
+ be the registered name. Now element <c>Object</c> 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 <c>'DOWN'</c> messages on
+ the new format even if they are monitoring processes on old
+ nodes. Processes on old nodes always get <c>'DOWN'</c>
+ messages on the old format.</p>
+ </note>
+
+ <taglist>
+ <tag>Monitoring a <marker id="monitor_process"/><c>process</c></tag>
+ <item>
+ <p>Creates monitor between the current process and another
+ process identified by <c><anno>Item</anno></c>, which can be a
+ <c>pid()</c> (local or remote), an atom <c>RegisteredName</c> or
+ a tuple <c>{RegisteredName, Node}</c> for a registered process,
+ located elsewhere.</p>
+ </item>
+
+ <tag>Monitoring a <marker id="monitor_port"/><c>port</c></tag>
+ <item>
+ <p>Creates monitor between the current process and a port
+ identified by <c><anno>Item</anno></c>, which can be a
+ <c>port()</c> (only local), an atom <c>RegisteredName</c> or
+ a tuple <c>{RegisteredName, Node}</c> for a registered port,
+ located on this node. Note, that attempt to monitor a remote port
+ will result in <c>badarg</c>.</p>
+ </item>
+
+ <tag>Monitoring a
+ <marker id="monitor_time_offset"/><c>time_offset</c></tag>
<item>
<p>Monitor changes in
<seealso marker="#time_offset/0">time offset</seealso>
@@ -3072,15 +3070,17 @@ os_prompt% </pre>
Note that you can observe the change of the time offset
when calling <c>erlang:time_offset()</c> before you
get the <c>'CHANGE'</c> message.</p>
-
</item>
</taglist>
+
<p>Making several calls to <c>monitor/2</c> for the same
- <c><anno>Item</anno></c> and/or <c><anno>Type</anno></c> is not
- an error; it results in as many independent monitoring instances.</p>
+ <c><anno>Item</anno></c> and/or <c><anno>Type</anno></c> is not
+ an error; it results in as many independent monitoring instances.</p>
+
<p>The monitor functionality is expected to be extended. That is,
- other <c><anno>Type</anno></c>s and <c><anno>Item</anno></c>s
- are expected to be supported in a future release.</p>
+ other <c><anno>Type</anno></c>s and <c><anno>Item</anno></c>s
+ are expected to be supported in a future release.</p>
+
<note>
<p>If or when <c>monitor/2</c> is extended, other
possible values for <c>Tag</c>, <c>Object</c> and
@@ -4150,6 +4150,22 @@ os_prompt% </pre>
<func>
<name name="port_info" arity="2" clause_i="8"/>
+ <fsummary>Which processes are monitoring this port.</fsummary>
+ <desc>
+ <p>Returns list of pids that are monitoring given port at the
+ moment.</p>
+ <p>If the port identified by <c><anno>Port</anno></c> is not open,
+ <c>undefined</c> 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
+ <c>port_info/2</c> returns <c>undefined</c>.</p>
+ <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local
+ port identifier, or an atom.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="port_info" arity="2" clause_i="9"/>
<fsummary>Information about the name of a port.</fsummary>
<desc>
<p><c><anno>Name</anno></c> is the command name set by
@@ -4165,7 +4181,7 @@ os_prompt% </pre>
</func>
<func>
- <name name="port_info" arity="2" clause_i="9"/>
+ <name name="port_info" arity="2" clause_i="10"/>
<fsummary>Information about the OS pid of a port.</fsummary>
<desc>
<p><c><anno>OsPid</anno></c> is the process identifier (or equivalent)
@@ -4184,7 +4200,7 @@ os_prompt% </pre>
</func>
<func>
- <name name="port_info" arity="2" clause_i="10"/>
+ <name name="port_info" arity="2" clause_i="11"/>
<fsummary>Information about the output of a port.</fsummary>
<desc>
<p><c><anno>Bytes</anno></c> is the total number of bytes written
@@ -4203,7 +4219,7 @@ os_prompt% </pre>
</func>
<func>
- <name name="port_info" arity="2" clause_i="11"/>
+ <name name="port_info" arity="2" clause_i="12"/>
<fsummary>Information about the parallelism hint of a port.</fsummary>
<desc>
<p><c><anno>Boolean</anno></c> corresponds to the port parallelism
@@ -4214,7 +4230,7 @@ os_prompt% </pre>
</func>
<func>
- <name name="port_info" arity="2" clause_i="12"/>
+ <name name="port_info" arity="2" clause_i="13"/>
<fsummary>Information about the queue size of a port.</fsummary>
<desc>
<p><c><anno>Bytes</anno></c> is the total number
@@ -4231,7 +4247,7 @@ os_prompt% </pre>
</func>
<func>
- <name name="port_info" arity="2" clause_i="13"/>
+ <name name="port_info" arity="2" clause_i="14"/>
<fsummary>Information about the registered name of a port.</fsummary>
<desc>
<p><c><anno>RegisteredName</anno></c> is the registered name of
@@ -4865,10 +4881,19 @@ os_prompt% </pre>
<p>A list of monitors (started by <c>monitor/2</c>)
that are active for the process. For a local process
monitor or a remote process monitor by a process
- identifier, the list item is <c>{process, <anno>Pid</anno>}</c>.
- For a remote process
- monitor by name, the list item is
- <c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c>.</p>
+ identifier, the list consists of:</p>
+ <taglist>
+ <tag><c>{process, <anno>Pid</anno>}</c></tag>
+ <item>Process is monitored by pid.</item>
+ <tag><c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c></tag>
+ <item>Local or remote process is monitored by name.</item>
+ <tag><c>{port, PortId}</c></tag>
+ <item>Local port is monitored by port id.</item>
+ <tag><c>{port, {<anno>RegName</anno>, <anno>Node</anno>}}</c></tag>
+ <item>Local port is monitored by name. Please note, that
+ remote port monitors are not supported, so <c>Node</c> will
+ always be the local node name.</item>
+ </taglist>
</item>
<tag><c>{message_queue_data, <anno>MQD</anno>}</c></tag>
<item>