mirror of
https://github.com/ubf/ubf.git
synced 2026-04-24 21:57:39 +00:00
194 lines
9.8 KiB
HTML
194 lines
9.8 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Module ubf_client</title>
|
|
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
|
|
</head>
|
|
<body bgcolor="white">
|
|
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
|
|
<hr>
|
|
|
|
<h1>Module ubf_client</h1>
|
|
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>UBF client-side public API.
|
|
|
|
|
|
<h2><a name="description">Description</a></h2><p>UBF client-side public API.</p>
|
|
|
|
This module implements most of the commonly-used client-side
|
|
functions required to talk to UBF servers:
|
|
<ul>
|
|
<li> connect() to a UBF server </li>
|
|
<li> rpc() to make a synchronous call to a connected UBF server </li>
|
|
<li> stop() a connection </li>
|
|
<li> install_handler() to add a callback function to handle
|
|
asynchronous notifications from theUBF server to your
|
|
client process. </li>
|
|
</ul>
|
|
|
|
<p>Note that this library can support UBF(A), EBF, JSF, TBF, PBF, and
|
|
ABF transport. See the <code>connect()</code> function arguments for
|
|
details.</p>
|
|
|
|
<p>This module also provides an alternative client-side function for
|
|
calling's UBF contract manager and a UBF contract's implementation
|
|
without any side-effects: <code>lpc()</code> to make a synchronous local
|
|
procedure call to a contract's implementation.</p>
|
|
|
|
See the documentation for the <tt>TBD</tt> module for extra
|
|
commentary on writing an UBF server implementation module.
|
|
|
|
<h2><a name="types">Data Types</a></h2>
|
|
|
|
<h3 class="typedecl"><a name="type-address">address()</a></h3>
|
|
<p><tt>address() = string() | <a href="#type-ip_address">ip_address()</a></tt></p>
|
|
<p>A DNS hostname or IP address.</p>
|
|
|
|
<h3 class="typedecl"><a name="type-connect_options">connect_options()</a></h3>
|
|
<p><tt>connect_options() = list({proto, ubf | ebf | jsf | tbf | pbf | abf})</tt></p>
|
|
<p>An OTP-style property list, see 'proplists' module for details.</p>
|
|
|
|
<h3 class="typedecl"><a name="type-ip_address">ip_address()</a></h3>
|
|
<p><tt>ip_address() = string() | tuple()</tt></p>
|
|
<p>An IP address in string form,
|
|
e.g. "127.0.0.1" (IPv4) or "::1" (IPv6), or in tuple form (see
|
|
documentation for Erlang's 'inet' module for details).</p>
|
|
|
|
<h3 class="typedecl"><a name="type-plugin_module_list">plugin_module_list()</a></h3>
|
|
<p><tt>plugin_module_list() = list(atom())</tt></p>
|
|
<p>A list of plugin module names
|
|
that will be passed to ubf_plugin_meta_stateful:new() or
|
|
ubf_plugin_meta_stateless:new() for client initialization.</p>
|
|
|
|
<h3 class="typedecl"><a name="type-tcp_port">tcp_port()</a></h3>
|
|
<p><tt>tcp_port() = integer()</tt></p>
|
|
<p>A TCP port number.</p>
|
|
|
|
<h3 class="typedecl"><a name="type-timeout">timeout()</a></h3>
|
|
<p><tt>timeout() = integer() | infinity</tt></p>
|
|
<p>An Erlang-style timeout value.</p>
|
|
|
|
<h2><a name="index">Function Index</a></h2>
|
|
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#connect-2">connect/2</a></td><td>Connect to a UBF server at address Host + TCP port Port.</td></tr>
|
|
<tr><td valign="top"><a href="#connect-3">connect/3</a></td><td>Connect to a UBF server at address Host + TCP port Port.</td></tr>
|
|
<tr><td valign="top"><a href="#connect-4">connect/4</a></td><td>Connect to a UBF server at address Host + TCP port Port, or at
|
|
pid/registered name Server.</td></tr>
|
|
<tr><td valign="top"><a href="#install_default_handler-1">install_default_handler/1</a></td><td>Install a default handler function (callback-style) for
|
|
asynchronous UBF messages.</td></tr>
|
|
<tr><td valign="top"><a href="#install_handler-2">install_handler/2</a></td><td>Install a handler function (callback-style) for asynchronous
|
|
UBF messages.</td></tr>
|
|
<tr><td valign="top"><a href="#lpc-2">lpc/2</a></td><td>Perform a synchronous LPC (local procedure) call with the
|
|
state 'none'.</td></tr>
|
|
<tr><td valign="top"><a href="#lpc-3">lpc/3</a></td><td>Perform a synchronous LPC (local procedure) call with the
|
|
specified state.</td></tr>
|
|
<tr><td valign="top"><a href="#lpc-4">lpc/4</a></td><td></td></tr>
|
|
<tr><td valign="top"><a href="#rpc-2">rpc/2</a></td><td>Perform a synchronous RPC call.</td></tr>
|
|
<tr><td valign="top"><a href="#rpc-3">rpc/3</a></td><td>Perform a synchronous RPC call.</td></tr>
|
|
<tr><td valign="top"><a href="#sendEvent-2">sendEvent/2</a></td><td>Send an asynchronous UBF message.</td></tr>
|
|
<tr><td valign="top"><a href="#stop-1">stop/1</a></td><td>Stop a UBF client process.</td></tr>
|
|
</table>
|
|
|
|
<h2><a name="functions">Function Details</a></h2>
|
|
|
|
<h3 class="function"><a name="connect-2">connect/2</a></h3>
|
|
<div class="spec">
|
|
<p><tt>connect(Host::<a href="#type-address">address()</a>, Port::<a href="#type-tcp_port">tcp_port()</a>) -> {ok, pid(), <a href="#type-service">service()</a>} | {error, term()}</tt></p>
|
|
</div><p>Connect to a UBF server at address Host + TCP port Port.</p>
|
|
|
|
<h3 class="function"><a name="connect-3">connect/3</a></h3>
|
|
<div class="spec">
|
|
<p><tt>connect(Host::<a href="#type-address">address()</a>, Port::<a href="#type-tcp_port">tcp_port()</a>, Timeout::<a href="#type-timeout">timeout()</a>) -> {ok, pid(), <a href="#type-service">service()</a>} | {error, term()}</tt></p>
|
|
</div><p>Connect to a UBF server at address Host + TCP port Port.</p>
|
|
|
|
<h3 class="function"><a name="connect-4">connect/4</a></h3>
|
|
<div class="spec">
|
|
<p><tt>connect(X::<a href="#type-address">address()</a> | <a href="#type-plugin_module_list">plugin_module_list()</a>, Y::<a href="#type-tcp_port">tcp_port()</a> | pid() | atom(), Options::<a href="#type-proplist">proplist()</a>, Timeout::<a href="#type-timeout">timeout()</a>) -> {ok, pid(), <a href="#type-service">service()</a>} | {error, term()}</tt></p>
|
|
</div><p><p>Connect to a UBF server at address Host + TCP port Port, or at
|
|
pid/registered name Server.</p>
|
|
|
|
When using the alternate form, the first two arguments are:
|
|
<ol>
|
|
<li> Plugins: a plugin_module_list(). </li>
|
|
<li> Server: either a process id (pid()) or process registered
|
|
name (atom()) for an already-started UBF server. </li>
|
|
</ol>
|
|
|
|
See the docs for ubf_server:start_link() for a description of the
|
|
<tt>Options</tt> proplist.</p>
|
|
|
|
<h3 class="function"><a name="install_default_handler-1">install_default_handler/1</a></h3>
|
|
<div class="spec">
|
|
<p><tt>install_default_handler(Pid::pid()) -> ack</tt></p>
|
|
</div><p><p>Install a default handler function (callback-style) for
|
|
asynchronous UBF messages.</p>
|
|
|
|
The default handler function, drop_fun/1, does nothing.</p>
|
|
|
|
<h3 class="function"><a name="install_handler-2">install_handler/2</a></h3>
|
|
<div class="spec">
|
|
<p><tt>install_handler(Pid::pid(), Fun::function()) -> ack</tt></p>
|
|
</div><p><p>Install a handler function (callback-style) for asynchronous
|
|
UBF messages.</p>
|
|
|
|
<p>The handler fun Fun should be a function of arity 1. When an
|
|
asynchronous UBF message is received, the callback function will be
|
|
called with the UBF message as its single argument. The Fun is
|
|
called by the ubf client process so the Fun can crash and/or block
|
|
this process.</p>
|
|
|
|
If your handler fun must maintain its own state, then you must use
|
|
an intermediate anonymous fun to bind the state. See the usage of
|
|
the <tt>irc_client_gs:send_self/2</tt> fun as an example. The
|
|
<tt>send_self()</tt> fun is actually arity 2, but the extra
|
|
argument is how the author, Joe Armstrong, maintains the extra
|
|
state required to deliver the async UBF message to the process that
|
|
is executing the event loop processing function,
|
|
<tt>irc_client_gs:loop/6</tt>.</p>
|
|
|
|
<h3 class="function"><a name="lpc-2">lpc/2</a></h3>
|
|
<div class="spec">
|
|
<p><tt>lpc(Mod::<a href="#type-module">module()</a>, Q::term()) -> term()</tt></p>
|
|
</div><p>Perform a synchronous LPC (local procedure) call with the
|
|
state 'none'.
|
|
</p>
|
|
|
|
<h3 class="function"><a name="lpc-3">lpc/3</a></h3>
|
|
<div class="spec">
|
|
<p><tt>lpc(Mod::<a href="#type-module">module()</a>, Q::term(), State::atom()) -> term()</tt></p>
|
|
</div><p>Perform a synchronous LPC (local procedure) call with the
|
|
specified state.
|
|
</p>
|
|
|
|
<h3 class="function"><a name="lpc-4">lpc/4</a></h3>
|
|
<div class="spec">
|
|
<p><tt>lpc(Mod, Q, State, TLogMod) -> any()</tt></p>
|
|
</div>
|
|
|
|
<h3 class="function"><a name="rpc-2">rpc/2</a></h3>
|
|
<div class="spec">
|
|
<p><tt>rpc(Pid::pid(), Q::term()) -> timeout | term()</tt></p>
|
|
</div><p><p>Perform a synchronous RPC call.</p>
|
|
|
|
NOTE: It is not recommended that a UBF client return the bare atom
|
|
'timeout' in response to any RPC call.</p>
|
|
|
|
<h3 class="function"><a name="rpc-3">rpc/3</a></h3>
|
|
<div class="spec">
|
|
<p><tt>rpc(Pid::pid(), Q::term(), Timeout::<a href="#type-timeout">timeout()</a>) -> timeout | term() | <a href="#type-exit">exit(badpid)</a> | <a href="#type-exit">exit(badarg)</a></tt></p>
|
|
</div><p>Perform a synchronous RPC call.</p>
|
|
|
|
<h3 class="function"><a name="sendEvent-2">sendEvent/2</a></h3>
|
|
<div class="spec">
|
|
<p><tt>sendEvent(Pid::pid(), Msg) -> any()</tt></p>
|
|
</div><p>Send an asynchronous UBF message.</p>
|
|
|
|
<h3 class="function"><a name="stop-1">stop/1</a></h3>
|
|
<div class="spec">
|
|
<p><tt>stop(Pid::pid()) -> ok</tt></p>
|
|
</div><p>Stop a UBF client process.</p>
|
|
<hr>
|
|
|
|
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
|
|
<p><i>Generated EDoc, $Id$</i></p>
|
|
</body>
|
|
</html>
|