Web Prolog manual

self(-Pid) is det.

Binds Pid to the process identifier of the calling process.

Note: The runtime uses a global pid model. Conceptually, pids are of the form Id@Node, although some compatibility-oriented surfaces, especially certain JSON responses, may still expose local pids as plain integers.

spawn(+Goal) is det.
spawn(+Goal, -Pid) is det.
spawn(+Goal, -Pid, +Options) is det.

Creates a new Web Prolog actor process running Goal. Valid options are:

• node(+URI)
  Creates the process locally or on a remote compatible node. Default is localhost.
• monitor(+Boolean)
  If true, monitoring is installed as part of process creation. Default is false.
• link(+Boolean)
  If true, installs directional parent-to-child link cleanup. Default is true.
• load_text(+AtomOrString)
  Loads the clauses specified by a Web Prolog source text into the actor's private Prolog database before calling Goal.
• load_list(+ListOfClauses)
  Converts the clauses to source text and loads them into the actor's private Prolog database before calling Goal.
• load_uri(+URI)
  Loads the clauses specified by a file path, file URI, or HTTP(S) URI into the actor's private Prolog database before calling Goal.
• load_predicates(+ListOfPredicateIndicators)
  Loads the local predicates denoted by ListOfPredicateIndicators into the actor's private Prolog database before calling Goal.

Note: In spawn(+Goal,-Pid,+Options), the option monitor(true) installs monitoring as part of process creation. When the child terminates, the parent receives a message down(Ref,Pid,Reason) where Pid is the terminated actor, Reason is its exit reason, and Ref identifies the monitor instance. For monitoring created via monitor(true), the current implementation uses Ref = Pid.

Note: The semantics of link(true) are directional: if a parent spawns a child with linking enabled, termination of the parent causes linked children to be terminated. The link does not imply symmetric bidirectional exit propagation.

Note: It is possible to pass an arbitrary number of the load_* options to spawn/3, and possibly more than one instance of each variant. To ensure that clauses end up in a well-defined order, they are converted into Prolog source text before being loaded into the database. The order of clauses and directives in the resulting source text is determined by the order of the load_* options in the option list.

actors(-Pids) is det.

Binds Pids to the list of actor pids visible from the current execution context. In ordinary public client execution, this means the current actor or toplevel together with any actors that have been spawned on behalf of the same client interaction. Actors belonging to other clients are not included.

Note: Outside public client execution, for example in node-owned runtime code or administrative code, actors/1 returns the pids of all active local actors on the node.

monitor(+PidOrName, -Ref) is det.

Installs a monitor and returns a fresh reference in Ref. The first argument may be a pid or a registered local name. When the monitored process terminates, the monitoring process receives a message of the form down(Ref,Pid,Reason).

demonitor(+Ref) is det.
demonitor(+Ref, +Options) is det.

Stops monitoring identified by Ref. This is idempotent. There is only one valid option:

• flush
  Non-blocking removal of one pending down(Ref,_,_) message from the mailbox.

Using monitor(true) in spawn/3 is the safest variant for short-lived children, since monitoring is established during spawn. Installing monitoring later with monitor/2 is a separate step and may miss a child that exits immediately.

register(+Name, +Pid) is det.

Register a local process under a name, where Name is an atom and Pid identifies the actor process. The association between the name and the pid is removed when the process terminates.

whereis(+Name, ?Pid) is det.

Determine the identity of the actor process associated with the name. Binds Pid to undefined if the process does not exist.

unregister(+Name) is det.

Remove the association between the name and the process.

exit(+Reason) is det.

Exit the calling process with Reason.

exit(+Pid, +Reason) is det.

Exit the process identified by Pid with Reason. For remote actors, the runtime routes this request through the remote node.

+PidOrName ! +Message is det.
send(+PidOrName, +Message) is det.
send(+PidOrName, +Message, +Options) is det.

Sends Message to the mailbox of the process identified as PidOrName. PidOrName may be a local pid, a local registered name, or a global pid of the form Id@Node. Valid options for send/3 are:

• delay(+Number)
  Delays the sending by a specified number of seconds. Default is 0.
• id(+ID)
ID is a user-supplied identifier that can be used by cancel/1 to stop the sending from taking place.

cancel(+ID) is det.

Tries to cancel the sending of all delayed messages with the specified ID. This is best-effort only, since a message may already have been sent by the time the call is made.

output(+Data) is det.
output(+Data, +Options) is det.

Sends a message output(Pid,Data) to the target process. Pid is the pid of the current process. Valid option:

• target(+Pid)
  Send the message to Pid. Default is the parent process.

Note that this is just a convenience predicate. A toplevel, like any other actor, may use !/2 to send any term to any process to which it has a pid.

input(+Prompt, -Data) is det.
input(+Prompt, -Data, +Options) is det.

Sends a message prompt(Pid,Prompt) to the target process and waits for its input. Prompt may be any non-variable term. Pid is the pid of the current process. Data will be bound to the term that the target process sends using respond/2. Valid option:

• target(+Pid)
  Send the prompt message to Pid. Default is the parent process.

respond(+Pid, +Input) is det.

Sends a response in the form of the term Input to a process that has prompted its parent process for input.

receive(+Clauses) is semidet.
receive(+Clauses, +Options) is semidet.

Clauses is a sequence of receive clauses delimited by a semicolon:

{  Pattern1 [if Guard1] ->
         Body1 ;
   ...
   PatternN [if GuardN] ->
         BodyN
}

Each pattern in turn is matched against the first message in the mailbox. If a pattern matches and the corresponding guard succeeds, the matching message is removed from the mailbox and the body of the receive clause is called. If no message is accepted, the process waits for new messages, checking them one at a time in arrival order. Messages that are not accepted are deferred, i.e. left in the mailbox without any change in their contents or order. Valid options:

• timeout(+Number)
  If nothing appears in the current mailbox within Number seconds, the predicate succeeds anyway. Default is no timeout.
• on_timeout(+Goal)
  If the timeout occurs, Goal is called.

flush is det.

Removes all messages currently pending in the mailbox of the calling process. Each removed message is rendered through the actor terminal-output path as a line of the form Shell got Message, where Message is the full Prolog term.

Note: flush/0 is primarily a shell-level inspection utility. It does not wait for future messages: once the mailbox is empty at the time of the call, it succeeds immediately.

listing is det.
listing(+Pid) is det.

listing/0 lists the content of the private database of the current actor process through the terminal-output path. Imported predicates and the injected I/O wrapper predicates are omitted.

listing/1 lists the content of the private database of the local actor identified by Pid. In public execution contexts this is namespace-scoped, so a client may only inspect actors that belong to its own session namespace.

toplevel_spawn(-Pid) is det.
toplevel_spawn(-Pid, +Options) is det.

Spawns a toplevel actor and binds Pid to its pid. All options accepted by spawn/3 are also accepted by toplevel_spawn/2. In addition, toplevel_spawn/2 accepts the following options:

• session(+Boolean)
  If set to false, the toplevel actor terminates after having run a goal to completion. If true, further interaction is expected. Default is false in the actor API.
• target(+Pid)
  Send all answer terms to Pid. Default is the pid of the parent.
• name(+Name)
  Register the toplevel under Name.

toplevel_call(+Pid, +Goal) is det.
toplevel_call(+Pid, +Goal, +Options) is det.

Asks the toplevel Pid for solutions to Goal. Valid options are:

• template(+Template)
Template is a term sharing variables with Goal. By default, the template is identical to the goal.
• offset(+Integer)
  Collect only the slice of solutions starting from Integer. Default is 0.
• limit(+Integer)
  Restrict the length of the returned list of solutions to Integer.
• once(+Boolean)
  When true, the list of solutions in a success answer term may not be the only solutions that Goal has, but the answer term may still indicate that it is. Default is false. Makes sense only in combination with the limit option.
• target(+Pid)
  Send the answer term to Pid. Default is the value of target when passed as an option to toplevel_spawn/2.

Variables in Goal are not bound directly in the caller. Instead, solutions and other kinds of output are returned in the form of answer messages delivered to the mailbox of the target process.

• success(Pid, Data, More)
Pid is the pid of the toplevel process that succeeded in finding solutions to Goal. Data is a list holding instantiations of Template. More is either true or false, indicating whether the toplevel can return more solutions if toplevel_next/1-2 is called.
• failure(Pid)
Pid is the pid of the toplevel process that failed for lack of solutions.
• error(Pid, Data)
Pid is the pid of the toplevel throwing the error. Data is the error term.

toplevel_next(+Pid) is det.
toplevel_next(+Pid, +Options) is det.

Asks toplevel Pid for more solutions. Valid options:

• limit(+Integer)
  If omitted, the actor API keeps using the most recent limit value from the previous toplevel call state.
• target(+Pid)
  Send the answer term to Pid. Default is the value of target from the previous call state.

The messages delivered to the target mailbox are the same as for toplevel_call/2-3.

toplevel_stop(+Pid) is det.

Asks toplevel Pid to stop searching for more solutions.

toplevel_abort(+Pid) is det.

Tells toplevel Pid to abort the execution of the currently running goal.

toplevel_halt(+Pid, -Reply) is det.

Sends '$halt' to an idle toplevel actor Pid, causing it to terminate from its idle state and acknowledge with Reply.

server_spawn(+Pred, +State, -Pid) is det.
server_spawn(+Pred, +State, -Pid, +Options) is det.

Spawns a generic server actor using callback predicate Pred/4 and initial state State. The callback receives (Request, OldState, Response, NewState).

All options are forwarded to spawn/3 except:

• name(+Name)
  Register the server under Name.

server_request(+To, +Request, -Response) is det.
server_request(+To, +Request, -Response, +Options) is det.

Makes a synchronous request-response call to the server To. server_request/4 accepts the options of receive/2, for example timeout(+Seconds).

Monitoring is installed automatically so the call fails fast if the server terminates before replying.

server_promise(+To, +Request, -Ref) is det.
server_promise(+To, +Request, -Ref, -MonRef) is det.

Sends Request to the server To and returns a correlation reference Ref. The reply must later be collected with server_yield/2-4.

The four-argument variant additionally installs a monitor and returns its reference in MonRef.

server_yield(+Ref, -Response) is det.
server_yield(+Ref, -Response, +Options) is det.
server_yield(+Ref, +MonRef, -Response, +Options) is det.

Waits for the response matching Ref. The three-argument variant accepts the options of receive/2.

The four-argument variant uses MonRef to detect server termination and throws server_down(Reason) if the server dies before replying.

server_upgrade(+To, +Pred) is det.

Replaces the callback predicate of the running server To without disturbing its current state. Pred must be arity 4.

server_halt(+To, -Reply) is det.

Asks the server To to stop gracefully and binds Reply to its acknowledgement.

statechart_spawn(-Pid) is det.
statechart_spawn(-Pid, +Options) is det.

Spawns a statechart actor and binds Pid to its pid.

statechart_spawn/2 requires exactly one source option:

• load_uri(+URI)
  Load and run a statechart from a URI or file path.
• load_text(+Text)
  Load and run a statechart from an XML text string.

In addition, statechart_spawn/2 accepts:

• name(+Name)
  Register the statechart actor under Name.

All remaining options are passed through to spawn/3.

load_list/1 and load_predicates/1 are rejected for statechart_spawn/2.

statechart_halt(+Pid, -Reply) is det.
statechart_halt(+Pid, -Reply, +Timeout) is det.

Asks the statechart actor Pid to halt gracefully and waits for an acknowledgement in Reply.

The three-argument form waits at most Timeout seconds. If the actor does not reply in time, it is killed and Reply becomes killed.

raise(+Event) is det.

Enqueues Event on the internal event queue of the current statechart interpreter.

Important: raise/1 is only meaningful inside executable statechart content such as <datamodel>, <onentry>, <onexit>, and <go>.

supervisor_spawn(+ChildSpecs, -Pid) is det.
supervisor_spawn(+ChildSpecs, -Pid, +Options) is det.

Spawns a supervisor actor and starts its children. Supported options are:

• strategy(+Strategy)
  One of one_for_one (default), one_for_all, or rest_for_one.
• intensity(+Integer)
  Max restarts in period. Default 1.
• period(+Integer)
  Window size for restart intensity. Default 5.
• name(+Name)
  Register the supervisor under Name.

Other options are passed through to spawn/3.

Child specifications take the form child(Id, ChildOptions). Child options are:

• start(+Goal)
  Required. Start goal for the child.
• restart(+Policy)
  One of permanent (default), transient, or temporary.
• shutdown(+Shutdown)
  One of brutal_kill, infinity, or a timeout number.
• type(+Type)
worker (default) or supervisor.

supervisor_spawn_child(+Pid, +ChildSpec, -Reply) is det.

Dynamically adds and starts one child. Reply is one of ok, error(already_present), or error(start_failed).

supervisor_terminate_child(+Pid, +Id, -Reply) is det.

Stops child Id but keeps its specification. Reply is ok or error(not_found).

supervisor_delete_child(+Pid, +Id, -Reply) is det.

Removes a non-running child specification. Reply is ok, error(running), or error(not_found).

supervisor_respawn_child(+Pid, +Id, -Reply) is det.

Restarts a previously terminated child from its stored specification. Reply is either ok(NewPid), error(running), error(not_found), or error(start_failed).

supervisor_which_children(+Pid, -Children) is det.

Returns a list of:

info(Id, Pid, Type, Restart)

where Pid may be undefined for stopped children.

supervisor_count_children(+Pid, -Counts) is det.

Returns:

[specs-N, active-N, supervisors-N, workers-N]

supervisor_halt(+Pid) is det.

Stops the supervisor and shuts down children in reverse start order.

rpc(+URI, +Goal) is nondet.
rpc(+URI, +Goal, +Options) is nondet.

Semantically, rpc/2-3 executes a copy of Goal on the remote node identified by URI and then unifies the local goal with the remote copy on backtracking. The current implementation uses the stateless /call endpoint. This matters: even if the remote node happens to be deployed as an ACTOR node, a call made through rpc/2-3 still runs against the node's stateless /call surface rather than its actor-facing APIs. Actor-only predicates such as self/1, spawn/1-3, and receive/1-2 are therefore not available through rpc/2-3. The following options are valid:

• limit(+Integer)
  Restricts the number of solutions retrieved per roundtrip.
• once(+Boolean)
  When true, the returned slice may not be the only solutions that Goal has, but the answer term may still indicate that it is.
• timeout(+Number)
  Requests a timeout in seconds for goal execution on the remote node. The effective timeout is the minimum of the requested value and the timeout configured by the node owner.
• http_timeout(+Number)
  Sets the client-side HTTP transport timeout in seconds for each request.
• load_text(+AtomOrString)
  Loads source text into the underlying actor's private database before calling Goal.
• load_list(+ListOfClauses)
  Loads a list of clauses into the underlying actor's private database before calling Goal.
• load_uri(+URI)
  Loads source text from URI into the underlying actor's private database before calling Goal.
• load_predicates(+ListOfPredicateIndicators)
  Loads the local predicates denoted by the supplied predicate indicators into the underlying actor's private database before calling Goal.

http_timeout/1 controls only the client-side HTTP transport timeout. It does not change the remote execution timeout.

promise(+URI, +Goal, -Ref) is det.
promise(+URI, +Goal, -Ref, +Options) is det.

Makes an asynchronous RPC call to node URI with Goal. The current implementation supports the following options:

• template(+Template)
Template is a term sharing variables with the goal. By default, the template is identical to the goal.
• offset(+Integer)
  Collect only the slice of solutions starting from Integer. Default is 0.
• limit(+Integer)
  Restrict the number of returned solutions to Integer.

The reference returned in Ref can later be used by yield/2-3 to collect the answer.

yield(+Ref, ?Answer) is det.
yield(+Ref, ?Answer, +Options) is det.

Returns the promised answer from a previous call to promise/3-4. This predicate must be called by the same process from which the previous call to promise/3-4 was made. Valid options:

• timeout(+Number)
  If nothing appears in the current mailbox within Number seconds, the goal supplied in the on_timeout option is called. Default is no timeout.
• on_timeout(+Goal)
  If the timeout occurs, Goal is called.