Changeset 10065 in project for release/3/rpc


Ignore:
Timestamp:
03/22/08 22:26:30 (12 years ago)
Author:
Kon Lovett
Message:

Save.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • release/3/rpc/tags/1.0.1/rpc.html

    r9973 r10065  
    11<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    2 <!-- Generated by eggdoc Revision: 1.17  -->
     2<!-- Generated by eggdoc Revision: 1.20  -->
    33<html>
    44<head>
     
    2626                    border-top: 1px solid #448;
    2727                    padding-left: 1em;
    28      }
     28                    margin-bottom: 1.2em;
     29     }
     30     DIV.subsubsection {
     31                    border-top: 1px dotted #99c;
     32                    /* border-left: 1px solid #99c; */
     33                    padding-left: 1em;
     34                    margin-bottom: 1.2em;
     35     }
     36     DIV.subsubsubsection {
     37                    border-top: 1px solid #ddf;
     38                    padding-left: 1em;
     39                    margin-bottom: 1.2em;
     40     }
     41
    2942         DIV.section {
    3043                 margin-bottom: 1.5em;
     
    4558                 margin: 0 0 1em 0;
    4659        }
    47         LI {
     60        UL LI {
    4861                list-style: none;
    4962        }
     
    5568                color: #113;
    5669                margin-bottom: 0.5em;
     70        }
     71        H4, H5, H6 {
     72                color: #113;
     73                margin-bottom: 1.0em;
     74        }
     75        H5 {
     76                font-weight: normal;
     77                font-style: italic;
     78                font-size: 100%;
     79                margin-top: 1.2em;
     80        }
     81        H6 {
     82                font-weight: bold;
     83                font-size: 85%;
     84                margin-top: 1.2em;
    5785        }
    5886     DIV#eggheader {
     
    101129       padding: 0.2em;
    102130       border: 1px solid #aac;
     131       border-collapse: collapse;
    103132       width: 100%;
    104133     }
     
    109138     }
    110139     TH {
    111        border-bottom: 1px solid black;
    112      } --></style></head>
     140       text-align: left;
     141       border-bottom: 1px solid #aac;
     142       padding: 0.25em 0.5em 0.25em 0.5em;
     143     }
     144     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
     145     --></style></head>
    113146<body>
    114147<div id="header">
    115148<h2>rpc</h2>
    116 <div id="eggheader">
    117 <a href="index.html">
     149<div id="eggheader"><a href="index.html">
    118150<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
    119151<div id="body">
     
    122154<p>A flexible peer-to-peer RPC system.</p></div>
    123155<div class="section">
    124 <h3>Author</h3>
    125 <a href="http://www.chust.org/">Thomas Chust</a></div>
     156<h3>Author</h3><a href="http://www.chust.org/">Thomas Chust</a></div>
    126157<div class="section">
    127158<h3>Version</h3>
     
    135166<li>Procedure tables</li></ul></div>
    136167<div class="section">
    137 <h3>Usage</h3>
    138 <tt>(require-extension rpc)</tt></div>
    139 <div class="section">
    140 <h3>Download</h3>
    141 <a href="rpc.egg">rpc.egg</a></div>
     168<h3>Usage</h3><tt>(require-extension rpc)</tt></div>
     169<div class="section">
     170<h3>Download</h3><a href="rpc.egg">rpc.egg</a></div>
    142171<div class="section">
    143172<h3>Documentation</h3>
    144173<p>This egg is a thin but flexible layer on top of tcp-server and s11n providing remote-procedure-call based communications. Special support for callbacks is provided, which makes the interface more a peer-to-peer than a client-server solution.</p>
    145174<div class="subsection">
    146 <p>
    147 <b>Managing published procedures</b></p>
     175<h4>Managing published procedures</h4>
    148176<dl>
    149 <dt class="definition">
    150 <strong>procedure:</strong> (rpc:publish-procedure! name procedure #!optional (callback-outgoing? #t)) =&gt; &lt;void&gt;</dt>
    151 <dd>
    152 <p>Registers
    153 <tt>procedure</tt> to be callable by incoming RPC requests under the name
    154 <tt>name</tt>. Names of procedures are matched using
    155 <tt>equal?</tt>.</p>
    156 <p>If
    157 <tt>callback-outgoing?</tt> is true, a reverse lookup entry associating the procedure with its name is also created. The table of reverse lookup entries is used by
    158 <tt>rpc:procedure</tt> to send a callback stub to the remote machine instead of the procedure itself, should the procedure be one of the parameters of a RPC call.</p></dd>
    159 <dt class="definition">
    160 <strong>procedure:</strong> (rpc:withdraw-procedure! name-or-procedure) =&gt; &lt;void&gt;</dt>
    161 <dd>
    162 <p>Unregisters the given
    163 <tt>name-or-procedure</tt> as an externally callable object. If a procedure is passed for the
    164 <tt>name-or-procedure</tt> parameter, it can only successfully be removed if a reverse lookup entry for this procedure exists.</p>
     177<dt class="definition"><strong>procedure:</strong> (rpc:publish-procedure! name procedure #!optional (callback-outgoing? #t)) =&gt; &lt;void&gt;</dt>
     178<dd>
     179<p>Registers <tt>procedure</tt> to be callable by incoming RPC requests under the name <tt>name</tt>. Names of procedures are matched using <tt>equal?</tt>.</p>
     180<p>If <tt>callback-outgoing?</tt> is true, a reverse lookup entry associating the procedure with its name is also created. The table of reverse lookup entries is used by <tt>rpc:procedure</tt> to send a callback stub to the remote machine instead of the procedure itself, should the procedure be one of the parameters of a RPC call.</p></dd>
     181<dt class="definition"><strong>procedure:</strong> (rpc:withdraw-procedure! name-or-procedure) =&gt; &lt;void&gt;</dt>
     182<dd>
     183<p>Unregisters the given <tt>name-or-procedure</tt> as an externally callable object. If a procedure is passed for the <tt>name-or-procedure</tt> parameter, it can only successfully be removed if a reverse lookup entry for this procedure exists.</p>
    165184<p>As mutex lock intervals are kept as short as possible, it may happen, that a currently active server thread calls the procedure once more immediately after its removal before it becomes completely unavailable to the outside world.</p></dd></dl></div>
    166185<div class="subsection">
    167 <p>
    168 <b>Managing connections</b></p>
     186<h4>Managing connections</h4>
    169187<dl>
    170 <dt class="definition">
    171 <strong>parameter:</strong> rpc:default-server-port</dt>
     188<dt class="definition"><strong>parameter:</strong> rpc:default-server-port</dt>
    172189<dd>
    173190<p>The standard port number to establish RPC connections to. The default value is 29296.</p></dd>
    174 <dt class="definition">
    175 <strong>parameter:</strong> rpc:connect-procedure</dt>
    176 <dd>
    177 <p>The procedure used to establish network connections for RPC. Defaults to
    178 <tt>tcp-connect</tt> and must be signature-compatible with it.</p></dd>
    179 <dt class="definition">
    180 <strong>procedure:</strong> (rpc:is-connected? host #!optional (port (rpc:default-server-port))) =&gt; &lt;boolean&gt;</dt>
    181 <dd>
    182 <p>Determines whether an RPC connection to the given
    183 <tt>host</tt> and
    184 <tt>port</tt> is active. The table of active connections is thread-local.</p></dd>
    185 <dt class="definition">
    186 <strong>procedure:</strong> (rpc:get-connection host #!optional (port (rpc:default-server-port))) =&gt; &lt;input-port&gt;, &lt;output-port&gt;</dt>
    187 <dd>
    188 <p>Retrieves an existing RPC connection to the given
    189 <tt>host</tt> and
    190 <tt>port</tt> or creates a new one. The table of active connections is thread-local.</p></dd>
    191 <dt class="definition">
    192 <strong>procedure:</strong> (rpc:close-connection! host #!optional (port (rpc:default-server-port))) =&gt; &lt;void&gt;</dt>
    193 <dd>
    194 <p>Closes an existing RPC connection to the given
    195 <tt>host</tt> and
    196 <tt>port</tt>. Fails if no such connection exists. The table of active connections is thread-local.</p></dd>
    197 <dt class="definition">
    198 <strong>procedure:</strong> (rpc:close-all-connections!) =&gt; &lt;void&gt;</dt>
     191<dt class="definition"><strong>parameter:</strong> rpc:connect-procedure</dt>
     192<dd>
     193<p>The procedure used to establish network connections for RPC. Defaults to <tt>tcp-connect</tt> and must be signature-compatible with it.</p></dd>
     194<dt class="definition"><strong>procedure:</strong> (rpc:is-connected? host #!optional (port (rpc:default-server-port))) =&gt; &lt;boolean&gt;</dt>
     195<dd>
     196<p>Determines whether an RPC connection to the given <tt>host</tt> and <tt>port</tt> is active. The table of active connections is thread-local.</p></dd>
     197<dt class="definition"><strong>procedure:</strong> (rpc:get-connection host #!optional (port (rpc:default-server-port))) =&gt; &lt;input-port&gt;, &lt;output-port&gt;</dt>
     198<dd>
     199<p>Retrieves an existing RPC connection to the given <tt>host</tt> and <tt>port</tt> or creates a new one. The table of active connections is thread-local.</p></dd>
     200<dt class="definition"><strong>procedure:</strong> (rpc:close-connection! host #!optional (port (rpc:default-server-port))) =&gt; &lt;void&gt;</dt>
     201<dd>
     202<p>Closes an existing RPC connection to the given <tt>host</tt> and <tt>port</tt>. Fails if no such connection exists. The table of active connections is thread-local.</p></dd>
     203<dt class="definition"><strong>procedure:</strong> (rpc:close-all-connections!) =&gt; &lt;void&gt;</dt>
    199204<dd>
    200205<p>Closes all existing RPC connections of the current thread.</p></dd></dl></div>
    201206<div class="subsection">
    202 <p>
    203 <b>Client and server frontend</b></p>
     207<h4>Client and server frontend</h4>
    204208<dl>
    205 <dt class="definition">
    206 <strong>parameter:</strong> rpc:current-peer</dt>
     209<dt class="definition"><strong>parameter:</strong> rpc:current-peer</dt>
    207210<dd>
    208211<p>Inside the server threads processing RPC requests, this parameter is set to the address (as a string) of the peer on behalf of which the thread is executing.</p>
    209 <p>
    210 <em>Consider this parameter read-only unless you really know what you are doing. You may seriously mess up communications otherwise.</em></p></dd>
    211 <dt class="definition">
    212 <strong>procedure:</strong> (rpc:procedure name host #!optional (port (rpc:default-server-port))) =&gt; &lt;procedure&gt;</dt>
    213 <dd>
    214 <p>Creates a procedure that can be called with any number of parameters to invoke the externally callable procedure published as
    215 <tt>name</tt> on the server at
    216 <tt>host:port</tt> with the given arguments.</p>
    217 <p>The arguments are scanned for procedures and if any such are found, those in the reverse lookup table are replaced with callback stubs before all the parameters are serialized over the network connection. Callback stubs are small procedures that use the value of the
    218 <tt>rpc:current-peer</tt> and
    219 <tt>rpc:default-server-port</tt> parameters in the remote server thread in order to determine where they came from and to use
    220 <tt>rpc:procedure</tt> again to connect back to their home and execute their real counterpart.</p>
     212<p><em>Consider this parameter read-only unless you really know what you are doing. You may seriously mess up communications otherwise.</em></p></dd>
     213<dt class="definition"><strong>procedure:</strong> (rpc:procedure name host #!optional (port (rpc:default-server-port))) =&gt; &lt;procedure&gt;</dt>
     214<dd>
     215<p>Creates a procedure that can be called with any number of parameters to invoke the externally callable procedure published as <tt>name</tt> on the server at <tt>host:port</tt> with the given arguments.</p>
     216<p>The arguments are scanned for procedures and if any such are found, those in the reverse lookup table are replaced with callback stubs before all the parameters are serialized over the network connection. Callback stubs are small procedures that use the value of the <tt>rpc:current-peer</tt> and <tt>rpc:default-server-port</tt> parameters in the remote server thread in order to determine where they came from and to use <tt>rpc:procedure</tt> again to connect back to their home and execute their real counterpart.</p>
    221217<p>Some care has been taken to isolate code executing in an RPC server thread properly:
    222218<ul>
    223219<li>Exceptions caused in the remotely executing code are caught, sent back to the client and rethrown there.</li>
    224 <li>The
    225 <tt>current-input-port, current-output-port</tt> and
    226 <tt>current-error-port</tt> parameters are changed for the remotely executing code.
    227 <tt>current-input-port</tt> never yields any input and the two output ports accumulate data into strings that are sent back to the client and printed on the
    228 <tt>current-output-port</tt> and
    229 <tt>current-error-port</tt> there.</li></ul></p></dd>
    230 <dt class="definition">
    231 <strong>procedure:</strong> (rpc:make-server listener) =&gt; &lt;procedure&gt;</dt>
    232 <dd>
    233 <p>Uses
    234 <tt>make-tcp-server</tt> to create a server procedure. The server threads spawned by this procedure are continuously processing RPC requests from their clients until the connection is closed.</p></dd></dl></div>
     220<li>The <tt>current-input-port, current-output-port</tt> and <tt>current-error-port</tt> parameters are changed for the remotely executing code. <tt>current-input-port</tt> never yields any input and the two output ports accumulate data into strings that are sent back to the client and printed on the <tt>current-output-port</tt> and <tt>current-error-port</tt> there.</li></ul></p></dd>
     221<dt class="definition"><strong>procedure:</strong> (rpc:make-server listener) =&gt; &lt;procedure&gt;</dt>
     222<dd>
     223<p>Uses <tt>make-tcp-server</tt> to create a server procedure. The server threads spawned by this procedure are continuously processing RPC requests from their clients until the connection is closed.</p></dd></dl></div>
    235224<div class="section">
    236225<h3>Examples</h3>
    237226<div id="examples">
    238227<p>This is a simple database server and client using sqlite3. As sqlite3 is not perfectly thread-safe and as there are of course better database servers around the example is perhaps a little academic, but it illustrates the use of this extension quite nicely.</p>
    239 <p>Note that in this example the
    240 <tt>rpc:default-server-port</tt> parameter in the server can be set by the client because the server does not know where the client is listening. In a similar way,
    241 <tt>rpc:current-peer</tt> may be reset if the client knows its public IP better than the server.</p><pre>
     228<p>Note that in this example the <tt>rpc:default-server-port</tt> parameter in the server can be set by the client because the server does not know where the client is listening. In a similar way, <tt>rpc:current-peer</tt> may be reset if the client knows its public IP better than the server.</p><pre>
    242229<i><font color="#B22222">;;;; rpc-demo.scm
    243230</font></i><i><font color="#B22222">;;;; Simple database server / client
     
    338325SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</pre></div></div></div>
    339326<div id="footer">
    340 <hr />
    341 <a href="index.html">&lt; Egg index</a>
     327<hr /><a href="index.html">&lt; Egg index</a>
    342328<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracChangeset for help on using the changeset viewer.