Message Pattern

When a message arrives at an agent, pattern match is conducted between an arrived message and registered message patterns. A message pattern can have its associated message handler. When a message which matches a message pattern arrives, its associated message handler is invoked.

Macro: define-message-pattern name-and-options pattern handler-body

name-and-options ::= name | (name options) 
options ::= (:documentation doc-string) 

The message pattern named name and its associated message handler are defined. pattern specifies the message pattern, and handler-body specifies the associated message handler. The syntax of pattern is as follows.

pattern ::= class receiver sender [ priority ] slots
class ::= symbol
receiver ::= wildcard-name | name | ( { name }+ ) | pattern-var
sender ::= wildcard-name | name | ( { name }+ ) | pattern-var
wildcard-name ::= "*" | * 
name ::= symbol | string

Note: When a symbol is given for name, pattern match is conducted based on its symbol-name using equalp as a comparison function. Note that an agent's name is case-insensitive.

priority ::= number | lisp-form-number
slots ::= { slot-name value-pattern }* 
slot-name ::= keyword
value-pattern ::= pattern-var | pattern-form | lisp-form-quoted 
                  | (value-pattern { value-pattern }*) 
pattern-var ::= (:? [ pattern-var-name ] [ :value-restriction value-restrictions ] 
                            [ :form-restriction lisp-form ] 
simple-pattern-var ::= (:?  pattern-var-name)
pattern-var-name ::= symbol
value-restrictions ::= ( { value-restriction }+)
value-restriction ::= (AND { value-restriction }+) | (OR { value-restriction }+)  
                      | (NOT value-restriction) | value-rest-prim
value-rest-prim ::= ( { > | >= | = | < | <= } lisp-form-number) | lisp-form 
pattern-form ::= (:! lisp-form)

lisp-form denotes a side-effect free lisp form in which simple-pattern-var can appear if simple-pattern-var is bound at the time of evaluation of lisp-form. lisp-form is evaluated when a pattern matching is done. lisp-form-number denotes lisp-form which must evaluate to a number. lisp-form-quoted is implicitly quoted in pattern; it is not evaluated during a pattern match. A priority is treated as a fixnum internally. If the given priority is not a fixnum, the number is truncated. The equal function in Common Lisp is used to compare values except receiver and sender.

In handler-body, msg, self, and context variables are implicitly declared. msg is bound to the message received, and self is bound to the receiver agent. context is bound to the current script executing context (see section Script Execution Context). In addition, in handler-body, pattern-var can appear if it also appears in pattern.

Example:

(define-message-pattern pattern1 
    (announcement * coordinator 1
                  :name "assessment" 
                  :time (:? x :value-restriction ((> 10))))
  (format t "Announcement ~s with time ~s is received by ~s" 
          msg (:? x) self))

This example means that if an announcement message sent from an agent named coordinator arrives, and if its name slot is "assessment" and its time slot is greater than 10, (format ...) is evaluated.

Generic Function: wait-for-message agent message-pattern &optional timeout &key :when-message-arrived :when-timeout

Primary Method: wait-for-message (agent agent) {(message-pattern message-pattern)} &optional timeout &key :when-message-arrived :when-timeout

The generic function wait-for-message blocks the agent execution until a message matching message-pattern arrives. If timeout is specified (i.e. non-nil), waiting is aborted after timeout seconds. Note that timeout should be a number or nil. When a matching message arrives and :when-message-arrived is a function, :when-message-arrived is called with arguments of a matching message and agent. When a timeout occurs and :when-timeout is a function, :when-timeout is called with agent as its argument.

Macro: define-message-pattern-template name-and-options lambda-list pattern

name-and-options ::= name | (name options) 
options ::= (:documentation doc-string) 

The macro define-message-pattern-template defines a message pattern template named name. This template allows slightly different message patterns to be defined from a single message pattern template, instead of defining many message patterns for various cases. When a message pattern template is created using the create-message-pattern-from-template function, lisp-forms in pattern are evaluated in the environment where variables in lambda-list are bound to the arguments in the invocation of create-message-pattern-from-template. Note that the evaluation of lisp-form in a message pattern is done when a pattern match occurs, not when the create-message-pattern-from-template function is called.

The following example shows the definition of a message pattern template which is used with wait-for-message. This template creates a message pattern which matches a reply message that is sent to receiver-name, and is sent from sender-name with its :reply-to slot is message-id.

Example:

(define-message-pattern-template wait-for-reply 
   (receiver-name sender-name message-id 
      &optional (priority *wait-for-reply-priority*))
   (reply (:! receiver-name) (:! sender-name) (:! priority)
          :reply-to (:! message-id)))

Function: create-message-pattern-from-template template-name &rest args

This function returns a message-pattern created from a message pattern template named template-name. args are used to initialize the template.

Function: set-message-pattern-priority message-pattern new-priority

This function modifies the priority of message-pattern to new-priority.

Generic Function: remove-message-pattern message-pattern

Primary Method: remove-message-pattern (message-pattern message-pattern)

Primary Method: remove-message-pattern (message-pattern-name symbol)

This method removes a message-pattern (either message-pattern itself or a message-pattern whose name is message-pattern-name).

Function: initialize-message-patterns &optional clear-all-p

This function initializes message pattern facility. When clear-all-p is non-nil, all the message patterns including system defined ones are cleared. clear-all-p should be nil unless you are debugging the AgenTalk system itself.