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

   Variant of recordz/2, suitable for thread communication

Arguments
   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

Type
   Recorded Database

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 --- Key, Timeout, or Max is not instantiated.
     5 --- Key is neither atom, compound term, nor record handle.
     5 --- Timeout is neither integer, float, nor the atom 'block'
     5 --- Max is not integer
     6 --- Timeout is a negative number
     6 --- Max is not positive
    45 --- 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
