[ 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

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).

See Also

record_create / 1, recordz / 2, record_wait_remove / 3