% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(tipc/tipc_linda): A Process Communication Interface}

\label{sec:tipclinda}

\begin{tags}
    \tag{author}
Jeffrey A. Rosenwald
    \tag{See also}
Nicholas Carriero and David Gelernter. \textit{How to Write Parallel
Programs: A First Course.} The MIT Press, Cambridge, MA, 1990.\mtag{Compatibility}- SWI-Prolog for Linux only \\- tipc_broadcast library
\end{tags}

Linda is a framework for building systems that are composed of programs
that cooperate among themselves in order to realize a larger goal. A
Linda application is composed of two or more processes acting in
concert. One process acts as a server and the others act as clients.
Fine-grained communications between client and server is provided by way
of message passing over sockets and support networks, TIPC sockets in
this case. Clients interact indirectly by way of the server. The server
is in principle an eraseable blackboard that clients can use to write
(\predref{out}{1}), read (\predref{rd}{1}) and remove (\predref{in}{1}) messages called \textit{tuples.} Some
predicates will fail if a requested tuple is not present on the
blackboard. Others will block until a tuple instance becomes available.
Tuple instances are made available to clients by writing them on the
blackboard using \predref{out}{1}.

In TIPC Linda, there is a subtle difference between the \const{in} and the
\const{rd} predicates that is worth noting. The \const{in} predicates succeed
exactly once for each tuple placed in the tuple space. The tuple is
provided to exactly one requesting client. Clients can contend for
tuples in this way, thus enabling multi-server operations. The \const{rd}
predicates succeed nondeterministically, providing all matching tuples
in the tuple space at a given time to the requesting client as a choice
point without disturbing them.

TIPC Linda is inspired by and adapted from the SICStus Prolog API. But
unlike SICStus TCP Linda, TIPC Linda is connectionless. There is no
specific session between client and server. The server receives and
responds to datagrams originated by clients in an epiperiodic manner.

Example: A simple producer-consumer.

In client 1:

\begin{code}
init_producer :-
       linda_client(global),
       producer.

producer :-
       produce(X),
       out(p(X)),
       producer.

produce(X) :- .....
\end{code}

In client 2:

\begin{code}
init_consumer :-
        linda_client(global),
        consumer.

consumer :-
       in(p(A)),
       consume(A),
       consumer.

consume(A) :- .....
\end{code}

Example: Synchronization

\begin{code}
       ...,
       in(ready),  %Waits here until someone does out(ready)
       ...,
\end{code}

Example: A critical region

\begin{code}
       ...,
       in(region_free),  % wait for region to be free
       critical_part,
       out(region_free), % let next one in
       ...,
\end{code}

Example: Reading global data

\begin{code}
       ...,
       rd(data(Data)),
       ...,
\end{code}

or, without blocking:

\begin{code}
       ...,
       (rd_noblock(data(Data)) ->
             do_something(Data)
       ;     write('Data not available!'),nl
       ),
       ...,
\end{code}

Example: Waiting for any one of several events

\begin{code}
       ...,
       in([e(1),e(2),...,e(n)], E),
%  Here is E instantiated to the first tuple that became available
       ...,
\end{code}

Example: Producers and Consumers in the same process using \verb$linda_eval$
threads and/or \const{tuple} predicates

\begin{code}
  consumer1 :-
        repeat,
        in([p(_), quit], Y),
        (   Y = p(Z) -> writeln(consuming(Z)); !),
        fail.

  producer1 :-
        forall(between(1,40, X), out(p(X))).

  producer_consumer1 :-
        linda_eval(consumer1),
        call_cleanup(producer1, out(quit)), !.
%
%
  consumer2 :-
       between(1,4,_),
       in_noblock(p(X)), !,
       writeln(consuming(X)),
       consumer2.

  producer2 :-
        linda_eval(p(X), between(1,40, X)).

  producer_consumer2 :-
        producer2,
        linda_eval(consumer2), !.
%
%
  consumer3 :-
        forall(rd_noblock(p(X)), writeln(consuming(X))).

  producer3 :-
        tuple(p(X), between(1,40, X)).

  producer_consumer3 :-
        producer3,
        linda_eval(done, consumer3),
        in(done), !.
\end{code}

\subsubsection{Servers}

\label{sec:tipc-linda-servers}

The server is the process running the "blackboard process". It is
part of TIPC Linda. It is a collection of predicates that are
registered as tipc_broadcast listeners. The server process can be run
on a separate machine if necessary.

To load the package, enter the query:

\begin{code}
?- use_module(library(tipc/tipc_linda)).

?- linda.
   TIPC Linda server now listening at: port_id('<1.1.1:3200515722>')
   true.
\end{code}

\subsubsection{Clients}

\label{sec:tipc-linda-clients}

The clients are one or more Prolog processes that have \verb$connection(s)$
to the server.

To load the package, enter the query:

\begin{code}
?- use_module(library(tipc/tipc_linda)).

?- linda_client(global).
   TIPC Linda server listening at: port_id('<1.1.1:3200515722>')
   true.
\end{code}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{linda}{0}{}
\nodescription
    \predicate[det]{linda}{1}{:Goal}
Starts a Linda-server in this process. The
network address is written to current output stream as a TIPC
\predref{port_id}{2} reference (e.g. \verb$port_id('<1.1.1:3200515722>')$ ). This
predicates looks to see if a server is already listening on the
cluster. If so, it reports the address of the existing server.
Otherwise, it registers a new server and reports its address.

\begin{code}
?- linda.
   TIPC Linda server now listening at: port_id('<1.1.1:3200515722>')
   true.

?- linda.
   TIPC Linda server still listening at: port_id('<1.1.1:3200515722>')
   true.
\end{code}

The following will call \predref{my_init}{0} in the current module after the
server is successfully started or is found already listening.
\predref{my_init}{0} could start client-processes, initialize the tuple space,
etc.

\begin{code}
?- linda(my_init).
\end{code}

    \predicate[semidet]{linda_client}{1}{+Domain}
Establishes a connection to a Linda-server providing a named tuple
space. \arg{Domain} is an atom specifying a particular tuple-space,
selected from a universe of tuple-spaces. At present however, only
one tuple-space, \const{global}, is supported. A client may interact with
any server reachable on the TIPC cluster. This predicate will fail
if no server is reachable for that tuple space.

    \predicate[det]{close_client}{0}{}
Closes the connection to the Linda-server. Causes the server to
release resources associated with this client.

    \predicate[semidet]{linda_timeout}{2}{?OldTime, ?NewTime}
Controls Linda's message-passing timeout. It specifies the time window
where clients will accept server replies in response to \const{in} and \const{rd}
requests. Replies arriving outside of this window are silently
ignored. \arg{OldTime} is unified with the old timeout and then timeout is
set to \arg{NewTime}. \arg{NewTime} is of the form Seconds:Milliseconds. A
non-negative real number, seconds, is also recognized. The default is
0.250 seconds. This timeout is thread local and is \textit{not} inherited
from its parent. New threads are initialized to the default.

\textbf{Note:} The synchronous behavior afforded by \predref{in}{1} and \predref{rd}{1}
is implemented by periodically polling the server. The poll rate is
set according to this timeout. Setting the timeout too small may
result in substantial network traffic that is of little value.

\begin{tags}
    \tag{throws}
\verb$error(feature_not_supported)$. SICStus Linda can
disable the timeout by specifying \const{off} as \arg{NewTime}. This feature does
not exist for safety reasons.
\end{tags}

    \predicate[semidet]{linda_timeout}{1}{+NewTime}
Temporarily sets Linda's timeout. Internally, the original timeout is
saved and then the timeout is set to \arg{NewTime}. \arg{NewTime} is as described
in \predref{linda_timeout}{2}. The original timeout is restored automatically on
cut of choice points, failure on backtracking, or uncaught exception.

    \predicate[det]{out}{1}{+Tuple}
Places a \arg{Tuple} in Linda's tuple-space.

    \predicate[det]{in}{1}{?Tuple}
Atomically removes the tuple \arg{Tuple} from Linda's tuple-space if it
is there. The tuple will be returned to exactly one requestor. If
no tuple is available, the predicate blocks until it is available
(that is, someone performs an \predref{out}{1}).

    \predicate[semidet]{in_noblock}{1}{?Tuple}
Atomically removes the tuple \arg{Tuple} from Linda's tuple-space if it
is there. If not, the predicate fails. This predicate can fail due
to a timeout.

    \predicate[det]{in}{2}{+TupleList, -Tuple}
As \predref{in}{1} but succeeds when any one of the tuples in \arg{TupleList} is
available. \arg{Tuple} is unified with the fetched tuple.

    \predicate[nondet]{rd}{1}{?Tuple}
Succeeds nondeterministically if \arg{Tuple} is available in the
tuple-space, suspends otherwise until it is available. Compare this
with \predref{in}{1}: the tuple is not removed.

    \predicate[nondet]{rd_noblock}{1}{?Tuple}
Succeeds nondeterministically if \arg{Tuple} is available in the
tuple-space, fails otherwise. This predicate can fail due to a
timeout.

    \predicate[nondet]{rd}{2}{?TupleList, -Tuple}
As \predref{in}{2} but provides a choice point that does not remove any
tuples.

    \predicate[nondet]{bagof_in_noblock}{3}{?Template, ?Tuple, -Bag}
\nodescription
    \predicate[nondet]{bagof_rd_noblock}{3}{?Template, ?Tuple, -Bag}
\arg{Bag} is the list of all instances of \arg{Template} such that \arg{Tuple} exists
in the tuple-space. The behavior of variables in \arg{Tuple} and \arg{Template}
is as in \predref{bagof}{3}. The variables could be existentially quantified
with \predref{\Shat}{2} as in \predref{bagof}{3}. The operation is performed as an atomic
operation. This predicate can fail due to a timeout. Example:
Assume that only one client is connected to the server and that the
tuple-space initially is empty.

\begin{code}
  ?- out(x(a,3)), out(x(a,4)), out(x(b,3)), out(x(c,3)).

  true.
  ?- bagof_rd_noblock(C-N, x(C,N), L).

  L = [a-3,a-4,b-3,c-3] .

  true.
  ?- bagof_rd_noblock(C, N^x(C,N), L).

  L = [a,a,b,c] .

  true.
\end{code}

    \predicate[det]{linda_eval}{1}{:Goal}
\nodescription
    \predicate[det]{linda_eval}{2}{?Head, :Goal}
\nodescription
    \predicate[det]{linda_eval_detached}{1}{:Goal}
\nodescription
    \predicate[det]{linda_eval_detached}{2}{?Head, :Goal}
Causes \arg{Goal} to be evaluated in parallel with a parent predicate. The
child thread is a full-fledged client, possessing the same
capabilities as the parent. Upon successful completion of \arg{Goal},
unbound variables are unified and the result is sent to the Linda
server via \predref{out}{1}, where it is made available to others. \predref{linda_eval}{2}
evaluates \arg{Goal}, then unifies the result with \arg{Head}, providing a means
of customizing the resulting output structure. In \predref{linda_eval}{1}, \arg{Head}, and
\arg{Goal} are identical, except that the module name for \arg{Head} is stripped
before output. If the child fails or receives an uncaught exception,
no such output occurs.

\textbf{Joining Threads:} Threads created using linda_eval/(1-2) are not allowed
to linger. They are joined (blocking the parent, if necessary) under
three conditions: backtracking on failure into an linda_eval/(1-2), receipt
of an uncaught exception, and cut of choice-points. Goals are
evaluated using \predref{forall}{2}. They are expected to provide
nondeterministic behavior. That is they may succeed zero or more
times on backtracking. They must however, eventually fail or succeed
deterministically. Otherwise, the thread will hang, which will
eventually hang the parent thread. Cutting choice points in the
parent's body has the effect of joining all children created by the
parent. This provides a barrier that guarantees that all child
instances of \arg{Goal} have run to completion before the parent proceeds.
Detached threads behave as above, except that they operate
independently and cannot be joined. They will continue to run while
the host process continues to run.

Here is an example of a parallel quicksort:

\begin{code}
qksort([], []).

qksort([X | List], Sorted) :-
      partition(@>(X), List, Less, More),
      linda_eval(qksort(More, SortedMore)),
      qksort(Less, SortedLess), !,
      in_noblock(qksort(More, SortedMore)),
      append(SortedLess, [X | SortedMore], Sorted).
\end{code}

    \predicate[det]{tuple}{1}{:Goal}
\nodescription
    \predicate[det]{tuple}{2}{?Head, :Goal}
registers \arg{Head} as a virtual tuple in TIPC Linda's tuple space. On
success, any client on the cluster may reference the tuple, \arg{Head},
using \predref{rd}{1} or \predref{rd_noblock}{1}. On reference, \arg{Goal} is executed by a
separate thread of execution in the host client's Prolog process. The
result is unified with \arg{Head}, which is then returned to the guest
client. As in linda_eval/(1-2) above, \arg{Goal} is evaluated using \predref{forall}{2}. The
virtual tuple is unregistered on backtracking into a tuple/(1-2),
receipt of uncaught exception, or cut of choice-points. In \predref{tuple}{1},
\arg{Head} and \arg{Goal} are identical, except that the module name is stripped
from \arg{Head}.

\textbf{Note:} A virtual tuple is an extension of the server. Even though
it is operating in the client's Prolog environment, it is restricted
in the server operations that it may perform. It is generally safe
for tuple predicates to perform \predref{out}{1} operations, but it is unsafe
for them to perform any variant of \const{in} or \const{rd}, either directly or
indirectly. This restriction is however, relaxed if the server and
client are operating in separate heavyweight processes (not threads)
on the node or cluster. This is most easily achieved by starting a
stand-alone Linda server somewhere on the cluster. See
\predref{tipc_linda_server}{0}, below.

    \predicate[nondet]{tipc_linda_server}{0}{}
Acts as a stand-alone Linda server. This predicate initializes the
TIPC stack and then starts a Linda server in the current thread. If
a client performs an \verb$out(server_quit)$, the server's Prolog
process will exit via \predref{halt}{1}. It is intended for use in scripting as
follows:

\begin{code}
swipl -q -g 'use_module(library(tipc/tipc_linda)),
       tipc_linda_server' -t 'halt(1)'
\end{code}

See also manual section 2.10.2.1 Using PrologScript.

\textbf{Note:} Prolog will return a non-zero exit status if this
predicate is executed on a cluster that already has an active
server. An exit status of zero is returned on graceful shutdown.

\begin{tags}
    \tag{throws}
error(\verb$permission_error(halt,thread,2)$,context(\predref{halt}{1},Only
from thread 'main')), if this predicate is executed in a thread
other than \const{main}.
\end{tags}

    \predicate[semidet]{tipc_initialize}{0}{}
See \qpredref{tipc}{tipc_initialize}{0}.
\end{description}