@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

25 lines (22 loc) • 14.1 kB

HTML

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Active modules — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="ExtendLang.html">↑</a><a class="lpdoc-navbutton" href="conc_aggregates.html">←</a><a class="lpdoc-navbutton" href="actmod_dist.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a></span><span><a href="ciaofulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> »<br/> </li><li><a href="ExtendLang.html">PART IV - Language extensions</a> »<br/> </li><li><a href=""><strong>Active modules</strong></a> ▾<ul><li><a href="actmod_dist.html">Distribution protocol for active modules</a></li><li><a href="actmod_process.html">Active module processes</a></li><li><a href="actmod_rt.html">actmod_rt (library)</a></li></ul></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Concurrency model and semantics">Concurrency model and semantics</a></li><ul><li><a href="#Query protocols">Query protocols</a></li><li><a href="#Side-effects">Side-effects</a></li><li><a href="#Distributed">Distributed</a></li></ul><li><a href="#Using active modules">Using active modules</a></li><li><a href="#Running active modules">Running active modules</a></li><li><a href="#Examples">Examples</a></li><li><a href="#Usage and interface">Usage and interface</a></li><li><a href="#Documentation on new declarations">Documentation on new declarations</a></li><li><a href="#Documentation on exports">Documentation on exports</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Active modules</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#actmod"></a> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Manuel Hermenegildo" href="ciaosearch.html#Manuel Hermenegildo">Manuel Hermenegildo</a>, <a class="lpdoc-idx-anchor" id="Daniel Cabeza" href="ciaosearch.html#Daniel Cabeza">Daniel Cabeza (original version before 1.16)</a>, <a class="lpdoc-idx-anchor" id="Jose F. Morales" href="ciaosearch.html#Jose F. Morales">Jose F. Morales (revised version)</a>.<p> <div class="lpdoc-alert"><strong>Stability: [</strong><strong>devel</strong><strong>] </strong>Currently the subject of active development and/or research. Functionality may be limited and API and/or functionality may change without warning or deprecation period. Not recommended yet for use in production.</div><p><br/> <p><div class="lpdoc-note"> This version corresponds to a revised model for active modules. See Ciao version 1.15 for the original first design as described in [<a class="lpdoc-idx-anchor" id="0" href="ciaorefs.html#ciao-dis-impl-parimp-www">CH95</a>]. </div> <p>An <a class="lpdoc-idx-anchor" id="1" href="ciaosearch.html#active module"><em>active module</em></a> is an ordinary module whose instances (copies sharing the same code but different state or data) have computational resources attached (e.g., computation steps shared in a fair fashion).<p>Active modules provide a high-level model of concurrency suitable for <a class="lpdoc-idx-anchor" id="2" href="ciaosearch.html#distributed execution">distributed execution</a> (and <a class="lpdoc-idx-anchor" id="3" href="ciaosearch.html#inter-process communication">inter-process communication</a>) that is similar to <a class="lpdoc-idx-anchor" id="4" href="ciaosearch.html#active object"><em>active object</em></a>s and <a class="lpdoc-idx-anchor" id="5" href="ciaosearch.html#actor"><em>actor</em></a>s. Note that Ciao also offers lower-level primitives for concurrency and network-based communication.<p><div id="Concurrency model and semantics"><h2>Concurrency model and semantics</h2> <p>Each <a class="lpdoc-idx-anchor" id="6" href="ciaosearch.html#active module instance"><em>active module instance</em></a> is internally composed of a local mailbox for queries (a queue of messages) and a query handler loop. Each active module instance is identified by a unique name (which can be provided or created automatically).<p>Calls to exported predicates of an active module are enqueued in the <a class="lpdoc-idx-anchor" id="7" href="ciaosearch.html#mailbox">mailbox</a>. The query handler loop is a <strong>deterministic</strong> loop that executes queries sequentially, sending back the results to the caller program (another active module instance) if needed. The composition of the (possibly) multiple answers from the callee and the caller is given be the <em>query protocols</em> defined below.<p><div class="lpdoc-note"> Query requests at the handler loop do not fail or leave choicepoints. When required, non-deterministic behaviour must be captured on the answer and treated on the callee by the <em>query protocols</em>. </div> <p><div id="Query protocols"><h3>Query protocols</h3> <p>There exist several query protocols depending on the expected answers of a predicate.<p><ul> <li><em>all solutions</em>: all answers to each query are precomputed on the callee side and sent to the caller. Backtracking is supported by enumeration on the caller side. <strong>Note</strong>: calls to active module predicates with an infinite number of solutions will obviously not terminate with this query method.<p><li><em>cast</em>: no answer is required from the callee (equivalent to <em>message passing</em> in distributed computation). It is useful when the query performs side-effects or it sends back the answers to the caller active module through another cast (a-la continuation-based programming).<p><li>(experimental) <em>answers with suspensions</em>: the callee may return a suspended computation and continue the execution on the caller site. Currently predicates must be declared as <tt>suspendable</tt>. The main focus of the current funcrionality is the implementation of <tt>REST</tt>ful applications via the (experimental) HTTP interface. <strong>Note</strong>: support is limited, recommended only for deterministic computations. </ul> <p>Further details on the semantics and concurrency model: <ul> <li>The cost of calls depends on the size of the messages (arguments, results, and the target <em>location</em>) <li>Deadlocks may happen due to the "message processing lock" (e.g., A calls B, B calls A). Use <em>cast</em> instead. </ul> <p><div class="lpdoc-note"> <ul> <li>Query protocols will be changed or extended in the future, specially to optimize cost for particular cases. <li>Suspendable predicates rely on the experimental <tt>fibers</tt> package. This may change in the future. <li>Or-suspensions for lazily asking for more solutions are not currently implemented (they are in development). </ul> </div> <p></div><div id="Side-effects"><h3>Side-effects</h3> <p>All communication between active module instances should (in principle) happen through message passing. Instances should not share any global data. Sharing via dynamic/data predicates (or other global mechanisms) is seen as an <em>impure</em> side-effect w.r.t. this model and must be used with care (e.g., <em>caching</em>, hand-made optimizations, etc.).<p></div><div id="Distributed"><h3>Distributed</h3> <p>In a distributed setting active module instances may run on separate <em>node</em>s that can interchange messages through the network. See <a class="lpdoc-idx-anchor" id="8" href="actmod_dist.html"><tt>actmod_dist</tt></a> for more details about the distribution protocol and how it can be extended.<p></div></div><div id="Using active modules"><h2>Using active modules</h2> <p>Using active modules requires the use of the <a class="lpdoc-idx-anchor" id="9" href=""><tt>actmod</tt></a> package: <pre class="lpdoc-codeblock">:- module(...,...,[actmod]). </pre> <p>This turns the current module into an active module and enables all the directives and features required to use other active modules.<p>Predicates exported by an active module can be accessed by other active modules using the <a class="lpdoc-idx-anchor" id="10" href="#use_module/3"><tt>use_module/3</tt></a> declaration with the <tt>active</tt> option (see below).<p>Note that the process of <em>using</em> an active module does not involve transferring any code, but rather setting up things so that calls in the module using the active module are executed as remote procedure calls to the active module.<p></div><div id="Running active modules"><h2>Running active modules</h2> <p>For spawning active module instances (dynamic creation) see <a class="lpdoc-idx-anchor" id="11" href="actmod_process.html"><tt>actmod_process</tt></a>.<p>Active modules may implement a <tt>main/1</tt> predicate, if they want to receive command-line arguments or use the directive <tt>:- dist_node</tt> to include a default <tt>main/1</tt> for distributed nodes. See <a class="lpdoc-idx-anchor" id="12" href="actmod_dist.html"><tt>actmod_dist</tt></a> for more details.<p></div><div id="Examples"><h2>Examples</h2> <p>The following command:<p><pre class="lpdoc-codeblock">ciaoc simple_server.pl </pre> <p>compiles the simple server example that comes with the distribution (in the <tt>actmod/example</tt> directory). The <tt>simple_client_with_main</tt> example (in the same directory) can be compiled as usual:<p><pre class="lpdoc-codeblock">ciaoc simple_client_with_main </pre> <p>Now, if the server is running when the client is executed it will connect with the server to access the predicate(s) that it imports from it.<p>An even simpler client <a class="lpdoc-idx-anchor" id="13" href="ciaosearch.html#simple_client.pl"><tt>simple_client.pl</tt></a> can be loaded into the top level and its predicates called as usual (and they will connect with the server if it is running). </div><br/><div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li><strong>Library usage:</strong><br/><tt>:- use_package(actmod).</tt> or <tt>:- module(...,...,[actmod]).</tt><li><strong>Exports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Regular Types:</em><br/><a class="lpdoc-idx-anchor" id="14" href="#import_opt/1"><tt>import_opt/1</tt></a>. </ul><li><strong>New declarations defined:</strong><br/><a class="lpdoc-idx-anchor" id="15" href="#use_module/3"><tt>use_module/3</tt></a>. <li><strong>Implicit imports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Packages:</em><br/><a class="lpdoc-idx-anchor" id="16" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="17" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="18" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="19" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="20" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>, <a class="lpdoc-idx-anchor" id="21" href="regtypes_doc.html"><tt>regtypes</tt></a>. </ul></ul></div></div><div id="Documentation on new declarations"><h2>Documentation on new declarations</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="use_module/3" href="ciaosearch.html#use_module/3">use_module/3</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>use_module(ModSpec,Imports,Opts)</tt>. </span><p>Import from <span class="lpdoc-var">ModSpec</span> the predicates in <span class="lpdoc-var">Imports</span> with options <span class="lpdoc-var">Opts</span>. If <span class="lpdoc-var">Imports</span> is a free variable, all predicates are imported.</p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="22" href="stream_basic.html#sourcename/1"><tt>stream_basic:sourcename/1</tt></a>)</span><span><span class="lpdoc-var">ModSpec</span> is a source name. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="23" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Imports</span> is a list of <span class="lpdoc-var">predname</span>s. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="24" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Opts</span> is a list of <span class="lpdoc-var">import_opt</span>s. </span> </ul></div></div><p> </div><div id="Documentation on exports"><h2>Documentation on exports</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="import_opt/1" href="ciaosearch.html#import_opt/1">import_opt/1</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>import_opt(Opt)</tt> </span><p>Options for <a class="lpdoc-idx-anchor" id="25" href="#use_module/3"><tt>use_module/3</tt></a>: <ul> <li><tt>active</tt>: import as an active module (which adds a dependency to the module interface, not its code; it allows <a class="lpdoc-idx-anchor" id="26" href="actmod_process.html#actmod_spawn/3"><tt>actmod_spawn/3</tt></a> and static named instances). <li><tt>reg_protocol(RegProtocol)</tt>: specify default name server protocol. <li><tt>libexec</tt>: use <tt>libexec</tt> as spawning option by default. <li><tt>binexec(Name)</tt>: use <tt>binexec(Name)</tt> as spawning option by default. </ul></div></div><p> </div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>