[ Operating System | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

wait(?Pid, ?Status)

Wait for a child process to terminate and report its process ID and status.

Pid: Integer or variable
Status: Integer or variable

Calling Modes

wait(+, ?)
wait(-, ?)

Description

This predicate is used to make the ECLiPSe process wait until a child process (created e.g. by exec/3 and identified by its process id Pid) terminates. Status is unified with the child process exit status.

A child process created with exec/3 still exists in the operating system even after it exits, as long as it was not waited for. Therefore it is advisable to use a wait/2 call after every exec/3 (note that exec/2 waits for the child process internally).

UNIX specific behaviour: The predicate can be invoked with Pid uninstantiated. In this case it will be resatisfiable and succeed once for every child process that terminates, as soon as a child process terminates, as long as there are child processes.

If the child process created by exec/3 or exec_group/3 could not be executed, the child exits with status 128 + errno.

When wait/2 is interrupted by a signal, the signal handler will be allowed to execute, and if it does not abort, wait/2 will be restarted subsequently.

When the child process terminated normally, then Status is the value that the child process exited with, multiplied by 256 (see wait(2)).

WINDOWS specific behaviour: The predicate can only be used to wait for one specific process, i.e. the Pid argument must be instantiated and the predicate is not resatisfiable.

A process that was created using exec_group/3 cannot be waited for.

When the child process terminated normally, then Status is the value that the child process exited with.

Fail Conditions

Fails if there are no child processes or the specified process does not exist

Resatisfiable

Yes.

Exceptions

(5) type error: Pid or Status are instantiated to non-integers.

Examples

Success:
    [eclipse]: exec([true], [], Pid), wait(Pid, Status).
    Pid = 3417
    Status = 0
    Yes (0.00s cpu)

    [eclipse]: exec([true], [], Pid), exec([date], [], Pid2), wait(Pid2, S2).
    Thu May 17 16:58:45 MET DST 1990

    Pid = 10617
    Pid2 = 10618
    S2 = 0
    Yes (0.00s cpu)


    % Unix only
    [eclipse 7]: exec([true],[],Pid1), exec([true],[],Pid2), wait(P,S).

    Pid1 = 13718
    Pid2 = 13719
    P = 13718
    S = 0
    More (0.00s cpu) ? ;

    Pid1 = 13718
    Pid2 = 13719
    P = 13719
    S = 0
    More (0.00s cpu) ? ;

    No (0.00s cpu)


Fail:
    [eclipse]: exec("true", [], Pid), wait(1111, S).

    No (0.00s cpu)


Example (UNIX only):

    % Kill the process in case the wait is aborted,
    % e.g. due to a timeout or after-event handler

    wait_with_cleanup(Pid, Status) :-
	block(
	    wait(Pid, Status),
	    Tag,
	    ( kill(Pid, 2), wait(Pid, _), exit_block(Tag) )
	).