7.7.1.2 Prolog Message Queues

 While Prolog predicates can communicate through shared dynamic code and tables, message queues provide a useful mechanism for one thread to pass a command to another or to synchronize on the return of data. A Prolog message queue can be defined to have a specified or default $size$ and can have any number of consumers and any number of producers. When a producer writes a $Term$ into a queue, the term is copied into the queue so that no binding are shared between $Term$ and the producer's stacks. $Term$ may include structures or lists and need not be bound, and any variable bindings within $Term$ are preserved. If the queue already contains $size$ elements, the producer will suspend until one or more elements are removed from the queue. When a consumer $T_{cons}$ accesses the queue it provides a goal $G$ and traverses the queue until it finds a term in the queue that unifies with $G$. If $T_{cons}$ finds a term in the queue that unifies with $G$, it removes it from the queue and continues in its computation. If there is no term in the queue that unifies with $G$, $T_{cons}$ will suspend until at least one other term is added to the queue. When it awakens it will retraverse the queue from the beginning to find a term that unifies with $G$ ^7.7. Because of the behavior of message queues, it is usually good programming practice to ensure that terms written into the queue will unify with the goals of consumers. This can usually be done by abstracting a consumers goal (say to a variable, X) or by splitting one ``multiplexed'' queue into two separate queues.

message_queue_create(-Queue,+Options)

mutex_xsb
Creates a new message queue with identifier Queue. Options allows optional parameters to be passed for the maximum number of terms in the queue, and for aliases of the queue.

• max_terms(N): create queue so that it can contain at most N terms before writes to the queue block. If not specified, the default size is used. This default can be queried and altered at run time via the XSB flag queue_max_terms. (cf. Section 6.11).
• alias(Alias): Allow queue Queue to be referred to via Alias in all standard queue predicates. Alias remains active for Queue until it is destroyed.

Error Cases

• Queue is not a variable
  • type_error(variable,Queue)
• Options is a partial list or a list with an element that is a variable
  • instantiation error
• Options is neither a partial list or a list
  • type error(list, Options)
• Options contains an option, Option not described above
  • domain_error(queue_option,Option)
• An element of Options is alias(A) and A is already associated with an existing thread, queue, mutex or stream
  • permission_error(create,alias, A)
• An element of Options is alias(A) and A is not an atom
  • type_error(atom,A)

message_queue_detroy(+Queue_or_Alias,#Message)

mutex_xsb
Destroys a message queue with alias or id Queue_or_alias, as created by message_queue_create/[1,2]. If any threads are currently waiting on Queue_or_Alias, an error will be thrown.

Error Cases

• Queue_or_Alias is a variable
  • instantiation_error
• Queue_or_Alias is not a queue id or alias
  • domain_error(queue_or_alias,Queue_or_Alias)

thread_send_message(+Queue_or_Alias,#Message)

mutex_xsb
If there are fewer terms on Queue_or_Alias than the queue's maximum allowed number thread_send_message/2 puts Message onto Queue_or_Alias, and returns immediately. Otherwise, the calling thread suspends until there are fewer elements on Queue_or_Alias than the queue's maximum allowed number, when the thread will be awakened to put Message onto the queue.

Error Cases

• Queue_or_Alias is a variable
  • instantiation_error
• Queue_or_Alias is not a queue id or alias
  • domain_error(queue_or_alias,Queue_or_Alias)

thread_get_message(+Queue_or_Alias,?Message)

mutex_xsb

If there are terms on Queue_or_Alias thread_get_message/2 traverses Queue_or_Alias to obtain the first term $T$ that unifies with Message. If $T$ exists, the predicate returns with Message bound to the most general unifier of Message and $T$. If there are no terms on Queue_or_Alias or if no terms unify with Message, the calling thread suspends until at least one term is added to Queue_or_Alias. When the thread awakes, it will recheck Queue from its beginning for a term that unifies with Message.

Error Cases

• Queue_or_Alias is a variable
  • instantiation_error
• Queue_or_Alias is not a queue id or alias
  • domain_error(queue_or_alias,Queue_or_Alias)