Merge branch 'kvakvs/erts/monitor_port/OTP-11384'

* kvakvs/erts/monitor_port/OTP-11384:
  erts: Add port monitors

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>