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

## See Also

record_create / 1, recordz / 2, record_wait_remove / 3