initial gen_server doc suggestiondgud/stdlib/gen-async-call

1 files changed, 72 insertions, 0 deletions

diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index da74e793e6..0e12a05df2 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -53,6 +53,7 @@ gen_server:start_link -----> Module:init/1
 gen_server:stop       -----> Module:terminate/2
 
 gen_server:call
+gen_server:async_call
 gen_server:multi_call -----> Module:handle_call/3
 
 gen_server:cast
@@ -175,6 +176,48 @@ gen_server:abcast     -----> Module:handle_cast/2
     </func>
 
     <func>
+      <name>async_call(ServerRef, Request) -> Promise</name>
+      <fsummary>Make a asynchronous call to a generic server.</fsummary>
+      <type>
+        <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName} | pid()</v>
+        <v>&nbsp;Node = atom()</v>
+        <v>&nbsp;GlobalName = ViaName = term()</v>
+        <v>Promise = reference()</v>
+        <v>Timeout = int()>0 | infinity</v>
+        <v>Request = term()</v>
+      </type>
+      <desc>
+        <p>Makes a asynchronous call to the <c>ServerRef</c> of the
+        <c>gen_server</c> process and returns a handle <c>Promise</c>.
+	The <c>gen_server</c> process calls
+        <seealso marker="#Module:handle_call/3">
+        <c>Module:handle_call/3</c></seealso> to handle the request.</p>
+        <p><c>ServerRef</c> can be any of the following:</p>
+        <list type="bulleted">
+          <item>The pid</item>
+          <item><c>Name</c>, if the <c>gen_server</c> process is locally
+            registered</item>
+          <item><c>{Name,Node}</c>, if the <c>gen_server</c> process is locally
+            registered at another node</item>
+          <item><c>{global,GlobalName}</c>, if the <c>gen_server</c> process is
+            globally registered</item>
+          <item><c>{via,Module,ViaName}</c>, if the <c>gen_server</c> process is
+            registered through an alternative process registry</item>
+        </list>
+        <p><c>Request</c> is any term that is passed as one of
+        the arguments to <c>Module:handle_call/3</c>.</p>
+        <p>The return value <c>Promise</c> is intended to be used with
+        <seealso marker="#yield/2"> <c>yield/1,2</c></seealso>.  Note,
+        if the reply message is received and kept without invoking
+        <seealso marker="#yield/2"> <c>yield/1,2</c></seealso>, the
+        monitor reference needs to be cleaned up with
+        <c>erlang:demonitor(Promise, [flush])</c>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
       <name>cast(ServerRef, Request) -> ok</name>
       <fsummary>Send an asynchronous request to a generic server.</fsummary>
       <type>
@@ -501,6 +544,35 @@ gen_server:abcast     -----> Module:handle_cast/2
     </func>
   </funcs>
 
+
+  <func>
+    <name>yield(Promise) -> {reply, Reply}</name>
+    <name>yield(Promise, Timeout) -> {reply, Reply} | timeout</name>
+    <fsummary>Wait for a reply from a server.</fsummary>
+    <type>
+      <v>Promise = reference()</v>
+      <v>Reply = term()</v>
+      <v>Timeout = timeout()</v>
+    </type>
+    <desc>
+      <p>This function is used to wait for a reply on a request made with
+      <seealso marker="#async_call/2"><c>async_call/2</c></seealso>
+      from the <c>gen_server</c> process.</p>
+      <p><c>Timeout</c> is an integer greater then or equal to zero
+      that specifies how many milliseconds to wait for an reply, or
+      the atom <c>infinity</c> to wait indefinitely. Defaults to
+      <c>infinity</c>.  If no reply is received within the specified
+      time, the function returns <c>timeout</c> and no cleanup is
+      done, and thus the function can be invoked repeatedly until a
+      reply is returned.  Otherwise do a cleanup the request with
+      <c>erlang:demonitor(Promise, [flush])</c>.</p>
+      <p>The return value <c>Reply</c> is defined in the return value
+      of <c>Module:handle_call/3</c>.</p>
+      <p>This function can fail for many reasons, including that the
+      called <c>gen_server</c> process dying before or during the call.</p>
+    </desc>
+  </func>
+
   <section>
     <title>Callback Functions</title>
     <p>The following functions