[ Recorded Database | Reference Manual | Alphabetic Index ]

record_wait_append(+Key, ?Value, +Timeout, +Max)

Variant of recordz/2, suitable for thread communication

Key: A record name (atom/compound) or handle.
Value: An arbitrary term.
Timeout: Timeout in seconds (integer or float), or the atom 'block'
Max: A positive integer, maximum number of recorded terms

Description

Like recordz/2, this predicate records the term Value at the end of the list of terms recorded under Key.

In addition, this predicate, together with record_wait_remove/3, implements a bounded queue with synchronisation between concurrent threads.

If there are already Max (or more) recorded terms in the queue, the predicate blocks until an invocation of record_wait_remove/3 (in another thread) reduces the queue length to below Max. If this does not happen within Timeout seconds, the predicate fails.

Conversely, adding a new entry with this predicate unblocks all currently blocking invocations of record_wait_remove/3 on the same Key.

Modes and Determinism

record_wait_append(+, ?, +, +) is semidet

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Fail Conditions

Fails if there are never less than Max records until Timeout expires

Exceptions

(4) instantiation fault: Key, Timeout, or Max is not instantiated.
(5) type error: Key is neither atom, compound term, nor record handle.
(5) type error: Timeout is neither integer, float, nor the atom 'block'
(5) type error: Max is not integer
(6) out of range: Timeout is a negative number
(6) out of range: Max is not positive
(45) named object does not exist: Key does is not a declared record name

Examples

% Produce data in the main engine, and send it via a record-queue
% to a concurrently running engine thread for consumption

    produce_consume(N) :-
	record_create(Q),
	engine_create(E, []),
	engine_resume_thread(E, consume(Q)),
	produce(Q, N).

    produce(Q, N) :-
	( for(I,1,N), param(Q) do
	    writeln(producing(I)),
	    record_wait_append(Q, I, block, 20)
	).

    consume(Q) :-
	record_wait_remove(Q, Msg, block),
	writeln(consuming(Msg)),
	consume(Q).