define-action

define-action Macro

Summary

Adds a new action to a specified list.

Package

lispworks

Signature

define-action name-or-list action-name data &rest specs

Arguments

`name-or-list`⇩	A list or action list object.
`action-name`⇩	A general lisp object.
`data`⇩	An object.
`specs`⇩	A list.

Description

The macro define-action adds a new action to the action list specified by name-or-list; this action will be executed according to the action-list's execution-function (see execute-actions) when executed. If the action-list specified by name-or-list does not exist, then this is handled according to the value of *handle-missing-action-list*.

name-or-list is evaluated to give either a list UID (to be looked up in the global registry of lists) or an action list object. action-name is a UID (general lisp object, to be compared by equalp). It uniquely identifies this action within its list (as opposed to among all lists).

data specifies an object referring to data relevant to the action.

specs is a free-form list of ordering specifiers and extra keywords, used to control more details of how and when this action is executed.

Action-items are normally expected not to be redefined. If an action-item with that action-name already exists in the action-list (that is, one with an identifier equalp to the action-name), then the notification and subsequent handling of this attempt is controlled by the values in the list *handle-existing-action-in-action-list*. This is to prevent problems due to re-evaluating an action definition inappropriately. Notification and redefine behavior can be overridden by using the :force keyword argument. In this case, any required redefinition is performed unconditionally and without notification.

The following keywords are recognized in specs:

`:after`	The following element in `specs` is a UID. `:after` specifies that the action-item being defined must be run after the action-item named. If there is no action-item with a matching name, the restriction is ignored.
`:before`	Like `:after`, but this action-item must be run before the one specified.

:after and :before can be specified as many times as necessary to describe the ordering constraints of this action-item with respect to its neighbors.

`:once`	Specifies that this action-item should be executed only once; after execution, it is disabled.
`:force`	Specifies that this definition should override any previous definition of this action-item, rather than be subject to the value of handle-existing-action-in-action-list.

Examples

(define-action :network-startup "Reset decnet buffers"
               '(decnet::reset-network-buffers 
                 *net-buffers*)
                :after "Reset core network"
                :once))