@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

51 lines • 18.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>Processes (multitasking) — 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="StdLibs.html">↑</a><a class="lpdoc-navbutton" href="pathnames.html">←</a><a class="lpdoc-navbutton" href="process_channel.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="StdLibs.html">PART VII - Standard libraries</a> »<br/> </li><li><a href=""><strong>Processes (multitasking)</strong></a> ▾<ul><li><a href="process_channel.html">Process channels</a></li></ul></li></ul><hr></hr><em>ON THIS PAGE</em><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>Processes (multitasking)</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#process"></a> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Jose F. Morales" href="ciaosearch.html#Jose F. Morales">Jose F. Morales</a>.<p> This library offers predicates to create, communicate, and synchronize with child processes. The child processes are duplicates of the parent process, based on the <tt>fork()</tt> function from POSIX-compatible operating systems (see <tt>man</tt> page for a precise description of the non-inherited process attributes).<p>The child process can execute a given goal (in a clone of the parent process) or start an external program.<p>Contrary to threads, processes have a separate address space and communication must be performed via inter-process communication mechanisms. This is useful for executing external programs, or implementing coarse-grained parallelism and concurrency.<p><div class="lpdoc-note"> <ul> <li>Process creation via <tt>fork()</tt> is relatively costly. Use only when address separation is necessary. Consider other concurrency primitives otherwise. <li>Channels connected to in-memory terms are transmited via pipes or temporary files (when needed to avoid deadlock problems). <li>Deadlock problems may still appear if the user specifies two or more <tt>pipe(_)</tt> channels for the same process (data must be send/received concurrently). <li>The current implementation is not protected against Prolog signals (it can leak resources, including zombie processes, if interrupted by signals). <li>Communication is currently only supported via file system, file descriptors, and sockets. <li>Other mechanisms like file locks, semaphores, message queues, shared memory, etc. are not yet implemented. <li>Arguments do not accept wildcards. See predicates in <a class="lpdoc-idx-anchor" id="0" href="ciaosearch.html#library(glob)"><tt>library(glob)</tt></a> for glob expansions (shell wildcard patterns). </ul> </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_module(library(process)).</tt><li><strong>Exports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Predicates:</em><br/><a class="lpdoc-idx-anchor" id="1" href="#process_call/3"><tt>process_call/3</tt></a>, <a class="lpdoc-idx-anchor" id="2" href="#process_pid/2"><tt>process_pid/2</tt></a>, <a class="lpdoc-idx-anchor" id="3" href="#process_is_joined/1"><tt>process_is_joined/1</tt></a>, <a class="lpdoc-idx-anchor" id="4" href="#process_join/1"><tt>process_join/1</tt></a>, <a class="lpdoc-idx-anchor" id="5" href="#process_terminate/1"><tt>process_terminate/1</tt></a>, <a class="lpdoc-idx-anchor" id="6" href="#process_kill/1"><tt>process_kill/1</tt></a>, <a class="lpdoc-idx-anchor" id="7" href="#process_send_signal/2"><tt>process_send_signal/2</tt></a>, <a class="lpdoc-idx-anchor" id="8" href="#process_fork/2"><tt>process_fork/2</tt></a>, <a class="lpdoc-idx-anchor" id="9" href="#process_pipe/2"><tt>process_pipe/2</tt></a>. <li><em>Regular Types:</em><br/><a class="lpdoc-idx-anchor" id="10" href="#process/1"><tt>process/1</tt></a>, <a class="lpdoc-idx-anchor" id="11" href="#process_option/1"><tt>process_option/1</tt></a>, <a class="lpdoc-idx-anchor" id="12" href="#process_cmd/1"><tt>process_cmd/1</tt></a>, <a class="lpdoc-idx-anchor" id="13" href="#process_arg/1"><tt>process_arg/1</tt></a>. </ul></ul></div></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="process/1" href="ciaosearch.html#process/1">process/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><p>A process handler</p><ul class="lpdoc-itemize-minus"></ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="process_option/1" href="ciaosearch.html#process_option/1">process_option/1</a></div><div class="lpdoc-deftext"><p>The predicate <a class="lpdoc-idx-anchor" id="14" href="#process_call/3"><tt>process_call/3</tt></a> waits for process completion, throwing an exception if the return code is different than <tt>0</tt>. This default exit behaviour can be controlled with the following options:<p><dl> <dt><tt>status(ReturnCode)</tt><dd> unifies return code with <span class="lpdoc-var">ReturnCode</span> upon process completion (no exception is thrown, may fail). <dt><tt>background(Process)</tt><dd> execute asynchronously in background; most errors (including input/output) are delayed to <a class="lpdoc-idx-anchor" id="15" href="#process_join/1"><tt>process_join/1</tt></a>. <dt><tt>setsid</tt><dd> call <tt>setsid()</tt> on the child to create a new session (useful to create daemon processes <a href="http://www.netzmafia.de/skripten/unix/linux-daemon-howto.html">http://www.netzmafia.de/skripten/unix/linux-daemon-howto.html</a>) </dl> <p>The process standard input, output, and error file descriptors (streams from the Prolog side) can be bound to several <a class="lpdoc-idx-anchor" id="16" href="process_channel.html#process_channel/1"><tt>process_channel/1</tt></a>:<p><dl> <dt><tt>stdin(Channel)</tt><dd> set channel for standard input <dt><tt>stdout(Channel)</tt><dd> set channel for standard output <dt><tt>stderr(Channel)</tt><dd> set channel for standard error </dl> <p>The environment of the process can be modified with the following options:<p><dl> <dt><tt>cwd(Dir)</tt><dd> execute command at the <span class="lpdoc-var">Dir</span> directory (does not affect relative path for input/output redirection). <dt><tt>env(Env)</tt><dd> modify the specified environment variables. <dt><tt>noenv(Env)</tt><dd> unset the specified environment variables. </dl> <p><span class="lpdoc-usage-header">Usage:</span><p>Options that control command execution</p><ul class="lpdoc-itemize-minus"></ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="process_cmd/1" href="ciaosearch.html#process_cmd/1">process_cmd/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><p>Command for <a class="lpdoc-idx-anchor" id="17" href="#process_call/3"><tt>process_call/3</tt></a></p><ul class="lpdoc-itemize-minus"></ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="process_arg/1" href="ciaosearch.html#process_arg/1">process_arg/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><p>Argument for <a class="lpdoc-idx-anchor" id="18" href="#process_call/3"><tt>process_call/3</tt></a></p><ul class="lpdoc-itemize-minus"></ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_call/3" href="ciaosearch.html#process_call/3">process_call/3</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_call(Cmd,Args,Opts)</tt> </span><p>Execute a command in a child process, where <span class="lpdoc-var">Cmd</span> is the executable path. Use <tt>path(Exec)</tt> for executing a program <span class="lpdoc-var">Exec</span> reachable from the <tt>PATH</tt> environment variable</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="20" href="#process_cmd/1"><tt>process:process_cmd/1</tt></a>)</span><span>Command for <a class="lpdoc-idx-anchor" id="19" href="#process_call/3"><tt>process_call/3</tt></a> </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="21" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Args</span> is a list of <span class="lpdoc-var">process_arg</span>s. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="22" 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">process_option</span>s. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_pid/2" href="ciaosearch.html#process_pid/2">process_pid/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_pid(Process,Pid)</tt> </span><p>The POSIX PID of the process <span class="lpdoc-var">Process</span>.</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="23" href="#process/1"><tt>process:process/1</tt></a>)</span><span>A process handler </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="24" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Pid</span> is an integer. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_is_joined/1" href="ciaosearch.html#process_is_joined/1">process_is_joined/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_is_joined(Process)</tt> </span><p>The process has already been joined.</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="25" href="#process/1"><tt>process:process/1</tt></a>)</span><span>A process handler </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_join/1" href="ciaosearch.html#process_join/1">process_join/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_join(Process)</tt> </span><p>Wait for completion of process <span class="lpdoc-var">Process</span>.</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="26" href="#process/1"><tt>process:process/1</tt></a>)</span><span>A process handler </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_terminate/1" href="ciaosearch.html#process_terminate/1">process_terminate/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_terminate(Process)</tt> </span><p>Sends POSIX signal SIGTERM to the process <span class="lpdoc-var">Process</span>, which asks politely for process termination.</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="27" href="#process/1"><tt>process:process/1</tt></a>)</span><span>A process handler </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_kill/1" href="ciaosearch.html#process_kill/1">process_kill/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_kill(Process)</tt> </span><p>Sends POSIX signal SIGKILL to the process <span class="lpdoc-var">Process</span>, which forces process termination.</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="28" href="#process/1"><tt>process:process/1</tt></a>)</span><span>A process handler </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_send_signal/2" href="ciaosearch.html#process_send_signal/2">process_send_signal/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_send_signal(Process,Signal)</tt> </span><p>Sends POSIX signal <span class="lpdoc-var">Signal</span> to process <span class="lpdoc-var">Process</span>.</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="29" href="#process/1"><tt>process:process/1</tt></a>)</span><span>A process handler </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="30" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">Signal</span> is an integer. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_fork/2" href="ciaosearch.html#process_fork/2">process_fork/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_fork(Goal,Opts)</tt> </span><p>Execute <span class="lpdoc-var">Goal</span> in a forked process.</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="31" href="basic_props.html#cgoal/1"><tt>basic_props:cgoal/1</tt></a>)</span><span><span class="lpdoc-var">Goal</span> is a term which represents a goal, i.e., an atom or a structure. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="32" 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">process_option</span>s. </span> </ul> <em>Meta-predicate</em> with arguments: <tt>process_fork(goal,?)</tt>.<br/></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="process_pipe/2" href="ciaosearch.html#process_pipe/2">process_pipe/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>process_pipe(Cmd,Opts)</tt> </span><p>Execute the list <span class="lpdoc-var">Cmds</span> of <a class="lpdoc-idx-anchor" id="33" href="#process_call/3"><tt>process_call/3</tt></a>, connecting standard input and output of consecutive processes with pipes.<p>Options are passed as follows: input redirection options are applied to the first process; output redirection and status are applied to the last process; the rest of options are applied to all commands. Background execution is not currently supported (see internal documentation for details).</p><ul class="lpdoc-itemize-minus"></ul></div></div><p> </div><div id="Documentation on imports"><h2>Documentation on imports</h2>This module has the following direct dependencies:<ul class="lpdoc-itemize-minus"><li><em>System library modules:</em><br/><a class="lpdoc-idx-anchor" id="34" href="lists.html"><tt>lists</tt></a>, <a class="lpdoc-idx-anchor" id="35" href="port_reify.html"><tt>port_reify</tt></a>, <a class="lpdoc-idx-anchor" id="36" href="system.html"><tt>system</tt></a>, <a class="lpdoc-idx-anchor" id="37" href="process_channel.html"><tt>process_channel</tt></a>. <li><em>Packages:</em><br/><a class="lpdoc-idx-anchor" id="38" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="39" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="40" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="41" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="42" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>, <a class="lpdoc-idx-anchor" id="43" href="regtypes_doc.html"><tt>regtypes</tt></a>, <a class="lpdoc-idx-anchor" id="44" href="isomodes_doc.html"><tt>isomodes</tt></a>, <a class="lpdoc-idx-anchor" id="45" href="ciaosearch.html#hiord"><tt>hiord</tt></a>. </ul></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>