[ library(hash) | Reference Manual | Alphabetic Index ]

# hash_insert_suspension(+Table, +Susp, -Notifications)

Attach a suspension to be woken on hash table modifications

Table
  Hash table
Susp
  A suspension
Notifications
  A receive port, see library(notify_ports)

## Description

Attach a suspension Susp to the hash table Table such that it gets woken whenever the table changes (i.e. when entries are added, changed or removed).

The suspended goal would typically be a demon (because it is going to be woken repeatedly, on every change). hash_insert_suspension/3 also supplies a Notifications argument, which should be used as one of the arguments of the suspended goal (see example). This is a "receive port" as defined by library(notify_ports), and is used to convey information about the changes that happened to the hash table. The notifications are of the following form:

add(Key,Value)
  if a table entry was added
chg(Key,OldValue,NewValue)
  if a table entry was modified
rem(Key,OldValue)
  if a table entry was removed

Note that the suspensions will be always be woken after the hash table has changed, so they will see the new state when they wake up.

### Modes and Determinism

- hash_insert_suspension(+, +, -) is det

## Examples

        % Program:

    	hash_create_verbose(H) :-
    	    hash_create(H),
    	    make_suspension(report(Notifications,Susp), 2, Susp),
    	    hash_insert_suspension(H, Susp, Notifications).

    	:- demon(report/2).
    	report(Notifications, Susp) :-
    	    notify_ports:receive_notifications(Notifications, List, Status),
    	    writeln(changes:List),
    	    ( Status = closed -> kill_suspension(Susp) ; true ).

        % Sample execution

        ?- hash_create_verbose(H),
           hash_set(H,k1,v1), hash_set(H,k1,v2), hash_delete(H,k1),
           hash_terminate_suspensions(H).
        changes : [add(k1, v1)]
        changes : [chg(k1, v1, v2)]
        changes : [rem(k1, v2)]
        changes : []

        H = hash(4, 0, [])
        Yes (0.00s cpu)

## See Also

hash_terminate_suspensions / 1, notify_ports : receive_notifications / 3, notify_ports : foreachnotification / 6, library(notify_ports), demon / 1