@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

95 lines • 28.9 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>Low-level concurrency/multithreading primitives — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton">☰</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"><a class="lpdoc-navbutton" href="ExtendLang.html">↑</a><a class="lpdoc-navbutton" href="factsdb_rt.html">←</a><a class="lpdoc-navbutton" href="conc_aggregates.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a><a href="ciaofulltoc.html">TOC</a></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> » </li><li><a href="ExtendLang.html">PART IV - Language extensions</a> » </li><li><a href="">Low-level concurrency/multithreading primitives</a></li></ul><hr></hr>ON THIS PAGE<ul><li><a href="#Usage and interface">Usage and interface</a></li><li><a href="#Documentation on exports">Documentation on exports</a></li><li><a href="#Documentation on imports">Documentation on imports</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Low-level concurrency/multithreading primitives</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#concurrency"></a> Author(s): <a class="lpdoc-idx-anchor" id="Manuel Carro" href="ciaosearch.html#Manuel Carro">Manuel Carro</a>. This module provides basic mechanisms for using concurrency and implementing multi-goal applications.<a class="lpdoc-idx-anchor" id="0" href="ciaosearch.html#concurrency"></a> It provides a means for arbitrary goals to be specified to be run in a separate stack set; in that case, they are assigned a goal identifier with which further accesses (e.g., asking for more solutions) to the goal can be made. Additionally, in some architectures, these goals can be assigned an O.S. thread, separate from the one which made the initial call, thus providing concurrency and, in multiprocessors, parallelism capabilities. <div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li>Library usage: <tt>:- use_module(library(concurrency)).</tt><li>Exports: <ul class="lpdoc-itemize-minus"><li>Predicates: <a class="lpdoc-idx-anchor" id="1" href="#eng_call/4"><tt>eng_call/4</tt></a>, <a class="lpdoc-idx-anchor" id="2" href="#eng_call/3"><tt>eng_call/3</tt></a>, <a class="lpdoc-idx-anchor" id="3" href="#eng_backtrack/2"><tt>eng_backtrack/2</tt></a>, <a class="lpdoc-idx-anchor" id="4" href="#eng_cut/1"><tt>eng_cut/1</tt></a>, <a class="lpdoc-idx-anchor" id="5" href="#eng_release/1"><tt>eng_release/1</tt></a>, <a class="lpdoc-idx-anchor" id="6" href="#eng_wait/1"><tt>eng_wait/1</tt></a>, <a class="lpdoc-idx-anchor" id="7" href="#eng_kill/1"><tt>eng_kill/1</tt></a>, <a class="lpdoc-idx-anchor" id="8" href="#eng_killothers/0"><tt>eng_killothers/0</tt></a>, <a class="lpdoc-idx-anchor" id="9" href="#eng_status/0"><tt>eng_status/0</tt></a>, <a class="lpdoc-idx-anchor" id="10" href="#eng_goal_id/1"><tt>eng_goal_id/1</tt></a>, <a class="lpdoc-idx-anchor" id="11" href="#lock_atom/1"><tt>lock_atom/1</tt></a>, <a class="lpdoc-idx-anchor" id="12" href="#unlock_atom/1"><tt>unlock_atom/1</tt></a>, <a class="lpdoc-idx-anchor" id="13" href="#atom_lock_state/2"><tt>atom_lock_state/2</tt></a>, <a class="lpdoc-idx-anchor" id="14" href="datafacts_rt.html#concurrent/1"><tt>concurrent/1</tt></a>. </ul></ul></div></div><div id="Documentation on exports"><h2>Documentation on exports</h2><div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_call/4" href="ciaosearch.html#eng_call/4">eng_call/4</a></div><div class="lpdoc-deftext">Usage:<tt>eng_call(Goal,EngineCreation,ThreadCreation,GoalId)</tt> Calls Goal in a new engine (stack set), possibly using a new thread, and returns a GoalId to designate this new goal henceforth. EngineCreation can be either <tt>wait</tt> or <tt>create</tt>; the distinction is not yet meaningful. ThreadCreation can be one of <tt>self</tt>, <tt>wait</tt>, or <tt>create</tt>. In the first case the creating thread is used to execute Goal, and thus it has to wait until its first result or failure. The call will fail if Goal fails, and succeed otherwise. However, the call will always suceed when a remote thread is started. The space and identifiers reclaimed for the thread must be explicitly deallocated by calling <a class="lpdoc-idx-anchor" id="15" href="#eng_release/1"><tt>eng_release/1</tt></a>. GoalIds are unique in each execution of a Ciao Prolog program.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="16" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)Goal is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="17" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)EngineCreation is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="18" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)ThreadCreation is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="19" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)GoalId is a free variable. (<a class="lpdoc-idx-anchor" id="20" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)Goal is a term which represents a goal, i.e., an atom or a structure. (<a class="lpdoc-idx-anchor" id="21" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)EngineCreation is an atom. (<a class="lpdoc-idx-anchor" id="22" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)ThreadCreation is an atom. (<a class="lpdoc-idx-anchor" id="23" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)GoalId is an integer. </ul> Meta-predicate with arguments: <tt>eng_call(goal,?,?,?)</tt>. </div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_call/3" href="ciaosearch.html#eng_call/3">eng_call/3</a></div><div class="lpdoc-deftext">Usage:<tt>eng_call(Goal,EngineCreation,ThreadCreation)</tt> Similar to <a class="lpdoc-idx-anchor" id="24" href="#eng_call/4"><tt>eng_call/4</tt></a>, but the thread (if created) and stack areas are automatically released upon success or failure of the goal. No GoalId is provided for further interaction with the goal.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="25" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)Goal is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="26" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)EngineCreation is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="27" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)ThreadCreation is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="28" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)Goal is a term which represents a goal, i.e., an atom or a structure. (<a class="lpdoc-idx-anchor" id="29" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)EngineCreation is an atom. (<a class="lpdoc-idx-anchor" id="30" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)ThreadCreation is an atom. </ul> Meta-predicate with arguments: <tt>eng_call(goal,?,?)</tt>. </div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_backtrack/2" href="ciaosearch.html#eng_backtrack/2">eng_backtrack/2</a></div><div class="lpdoc-deftext">Usage:<tt>eng_backtrack(GoalId,ThreadCreation)</tt> Performs backtracking on the goal designed by GoalId. A new thread can be used to perform backtracking, according to ThreadCreation (same as in <a class="lpdoc-idx-anchor" id="31" href="#eng_call/4"><tt>eng_call/4</tt></a>). Fails if the goal is backtracked over by the local thread, and there are no more solutions. Always succeeds if executed by a remote thread. The engine is not automatically released up upon failure: <a class="lpdoc-idx-anchor" id="32" href="#eng_release/1"><tt>eng_release/1</tt></a> must be called to that end.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="33" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)GoalId is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="34" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)ThreadCreation is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="35" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)GoalId is an integer. (<a class="lpdoc-idx-anchor" id="36" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)ThreadCreation is an atom. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_cut/1" href="ciaosearch.html#eng_cut/1">eng_cut/1</a></div><div class="lpdoc-deftext">Usage:<tt>eng_cut(GoalId)</tt> Performs a cut in the execution of the goal GoalId. The next call to <a class="lpdoc-idx-anchor" id="37" href="#eng_backtrack/2"><tt>eng_backtrack/2</tt></a> will therefore backtrack all the way and fail.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="38" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)GoalId is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="39" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)GoalId is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_release/1" href="ciaosearch.html#eng_release/1">eng_release/1</a></div><div class="lpdoc-deftext">Usage:<tt>eng_release(GoalId)</tt> Cleans up and releases the engine executing the goal designed by GoalId. The engine must be idle, i.e., currently not executing any goal. <a class="lpdoc-idx-anchor" id="40" href="#eng_wait/1"><tt>eng_wait/1</tt></a> can be used to ensure this.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="41" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)GoalId is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="42" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)GoalId is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_wait/1" href="ciaosearch.html#eng_wait/1">eng_wait/1</a></div><div class="lpdoc-deftext">Usage:<tt>eng_wait(GoalId)</tt> Waits for the engine executing the goal denoted by GoalId to finish the computation (i.e., it has finished searching for a solution, either with success or failure).<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="43" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)GoalId is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="44" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)GoalId is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_kill/1" href="ciaosearch.html#eng_kill/1">eng_kill/1</a></div><div class="lpdoc-deftext">Usage:<tt>eng_kill(GoalId)</tt> Kills the thread executing GoalId (if any), and frees the memory used up by the stack set. Usually one should wait (<a class="lpdoc-idx-anchor" id="45" href="#eng_wait/1"><tt>eng_wait/1</tt></a>) for a goal, and then release it, but killing the thread explicitly allows recovering from error states. A goal cannot kill itself. This feature should be used with caution, because there are situations where killing a thread might render the system in an unstable state. Threads should cooperate in their killing, but if the killed thread is blocked in a I/O operation, or inside an internal critical region, this cooperation is not possible and the system, although stopped, might very well end up in a incosistent state.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="46" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)GoalId is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="47" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)GoalId is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_killothers/0" href="ciaosearch.html#eng_killothers/0">eng_killothers/0</a></div><div class="lpdoc-deftext">Usage:Kills threads and releases stack sets of all active goals, but the one calling <a class="lpdoc-idx-anchor" id="48" href="ciaosearch.html#eng_killothers"><tt>eng_killothers</tt></a>. Again, a safety measure. The same cautions as with <a class="lpdoc-idx-anchor" id="49" href="#eng_kill/1"><tt>eng_kill/1</tt></a> should be taken.<ul class="lpdoc-itemize-minus"></ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_status/0" href="ciaosearch.html#eng_status/0">eng_status/0</a></div><div class="lpdoc-deftext">Usage:Prints to standard output the current status of the stack sets.<ul class="lpdoc-itemize-minus"></ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="eng_goal_id/1" href="ciaosearch.html#eng_goal_id/1">eng_goal_id/1</a></div><div class="lpdoc-deftext">Usage:<tt>eng_goal_id(GoalId)</tt> GoalId is unified with the identifier of the goal within which <a class="lpdoc-idx-anchor" id="50" href="#eng_goal_id/1"><tt>eng_goal_id/1</tt></a> is executed.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="51" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)GoalId is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="lock_atom/1" href="ciaosearch.html#lock_atom/1">lock_atom/1</a></div><div class="lpdoc-deftext">Usage 1:<tt>lock_atom(Atom)</tt> The <a class="lpdoc-idx-anchor" id="52" href="ciaosearch.html#semaphore">semaphore</a> associated to Atom is accessed; if its value is nonzero, it is atomically decremented and the execution of this thread proceeds. Otherwise, the goal waits until a nonzero value is reached. The semaphore is then atomically decremented and the execution of this thread proceeds.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="53" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)Atom is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="54" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Atom is an integer. </ul>Usage 2:<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="55" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Arg1 is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="unlock_atom/1" href="ciaosearch.html#unlock_atom/1">unlock_atom/1</a></div><div class="lpdoc-deftext">Usage 1:<tt>unlock_atom(Atom)</tt> The <a class="lpdoc-idx-anchor" id="56" href="ciaosearch.html#semaphore">semaphore</a> associated to Atom is atomically incremented.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="57" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)Atom is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="58" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Atom is an integer. </ul>Usage 2:<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="59" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Arg1 is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="atom_lock_state/2" href="ciaosearch.html#atom_lock_state/2">atom_lock_state/2</a></div><div class="lpdoc-deftext">Usage 1:<tt>atom_lock_state(Atom,Value)</tt> Sets the semaphore associated to Atom to Value. This is usually done at the beginning of the execution, but can be executed at any time. If not called, semaphore associated to atoms are by default inited to 1. It should be used with caution: arbitrary use can transform programs using locks in a mess of internal relations. The change of a semaphore value in a place other than the initialization stage of a program is not among the allowed operations as defined by Dijkstra [<a class="lpdoc-idx-anchor" id="60" href="ciaorefs.html#dijkstra-semaphores">Dij65</a>,<a class="lpdoc-idx-anchor" id="61" href="ciaorefs.html#ben-ari">BA82</a>].<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="62" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)Atom is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="63" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)Value is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="64" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Atom is an integer. (<a class="lpdoc-idx-anchor" id="65" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Value is an integer. </ul>Usage 2:<tt>atom_lock_state(Atom,Value)</tt> Consults the Value of the semaphore associated to Atom. Use sparingly and mainly as a medium to check state correctness. Not among the operations on semaphore by Djikstra.<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="66" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)Atom is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="67" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)Value is a free variable. (<a class="lpdoc-idx-anchor" id="68" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)Atom is an atom. (<a class="lpdoc-idx-anchor" id="69" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Value is an integer. </ul>Usage 3:<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="70" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Arg1 is an integer. (<a class="lpdoc-idx-anchor" id="71" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Arg2 is an integer. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="concurrent/1" href="ciaosearch.html#concurrent/1">concurrent/1</a></div><div class="lpdoc-deftext"><tt>concurrent(PredName)</tt> The predicate named PredName is made <a class="lpdoc-idx-anchor" id="72" href="ciaosearch.html#concurrent">concurrent</a> in the current module at runtime (useful for predicate names generated on-the-fly). This difficults a better compile-time analysis, but in turn offers more flexibility to applications. It is also faster for some applications: if several agents have to share data in a stuctured fashion (e.g., the generator knows and wants to restrict the data generated to a set of other threads), a possibility is to use the same concurrent fact and emply a field within the fact to distinguish the receiver/sender. This can cause many threads to access and wait on the same fact, which in turns can create contention problems. It is much better to create a new concurrent fact and to use that new name as a channel to communicate the different threads. <a class="lpdoc-idx-anchor" id="73" href="datafacts_rt.html#concurrent/1"><tt>concurrent/1</tt></a> can either be given a <a class="lpdoc-idx-anchor" id="74" href="ciaosearch.html#predicate spec">predicate spec</a> in the form Name/Arity, with Name and Arity bound, or to give a value only to Arity, and let the system choose a new, unused Name for the fact.Usage:<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="75" href="basic_props.html#predname/1"><tt>basic_props:predname/1</tt></a>)PredName is a predicate name. </ul></div></div> </div><div id="Documentation on imports"><h2>Documentation on imports</h2>This module has the following direct dependencies:<ul class="lpdoc-itemize-minus"><li>System library modules: <a class="lpdoc-idx-anchor" id="76" href="datafacts_rt.html"><tt>datafacts_rt</tt></a>. <li>Packages: <a class="lpdoc-idx-anchor" id="77" href="noprelude_doc.html"><tt>noprelude</tt></a>, <a class="lpdoc-idx-anchor" id="78" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="79" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="80" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="81" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>, <a class="lpdoc-idx-anchor" id="82" href="isomodes_doc.html"><tt>isomodes</tt></a>, <a class="lpdoc-idx-anchor" id="83" href="datafacts_doc.html"><tt>datafacts</tt></a>. </ul></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>