[ Event Handling | Reference Manual | Alphabetic Index ]

cancel_after_event(+Event, -CancelledEvents)

Cancel all pending instances of after event Event
Event
Atom or Handle
CancelledEvents
Variable

Description

All instances of the pending after event Event is cancelled so that the event will not be triggered. A pending after event is an event which is setup by either event_after/2, event_after/3 or event_after_every/2, and which is waiting to be raised (event_after_every/2 will always be pending as it is raised repeatedly).

CancelledEvents is the list of after events that have been cancelled. Each element of CancelledEvents is of the form of an event specified in Events of events_after / 1. As a result, CancelledEvents can be reposted using events_after(CancelledEvents). If there was no event to cancel, CancelledEvents will be bound to the empty list.

Note that the processing of an already raised, but as yet unprocessed event will not be cancelled by this predicate (but you can use event_disable/1 to achieve this).

Modes and Determinism

Exceptions

(5) type error
Event is not an atom.

Examples

    % setup an after event and cancel immediatedly
    ?- event_create(writeln(hi), [], E),
	event_after(E, 3.2),
	cancel_after_event(E, Cancelled).
    E = 'EVENT'(16'ed980a58)
    Cancelled = ['EVENT'(16'ed980a58) - 3.1999999999999886]
    Yes (0.00s cpu)

    % no after-event requested, nothing to cancel
    ?- event_create(writeln(hi), [], E),
	cancel_after_event(E, Cancelled).
    E = 'EVENT'(16'ed980a58)
    Cancelled = []
    Yes (0.00s cpu)

    % setup an after event and cancel immediatedly
    ?- event_create(writeln(hi), [], E1),
	event_after_every(E1, 1),
	event_create((cancel_after_event(E1, C1), writeln(cancelled(C1))), [], E2),
	event_after(E2, 5),
	repeat, fail.
    hi
    hi
    hi
    hi
    cancelled(['EVENT'(16'edbc0cc0) - every(1)])

See Also

event_after / 2, event_after / 3, event_disable / 1, event_after_every / 2, event / 1, set_event_handler / 2, current_after_events / 1, event_create / 3, event_retrieve / 3