25.1 Overview

This chapter discusses Libmarpa’s events. It contains descriptions of both grammar and recognizer methods.

A method is event-triggering iff it can add event instances to the event queue. The event-triggering methods are marpa_g_precompute(), marpa_r_earleme_complete(), and marpa_r_start_input(). The event-triggering methods always clear all previous events so that, on return from an event-triggering method, the only events in the event queue will be the events triggered by that method.

Every event instance has a type, and a subtype. The type of an event instance is its code, such as MARPA_EVENT_SYMBOL_COMPLETED. Event codes are listed in a later section. See Event codes. Subtypes will be described shortly.

Event types are either implicit or explicit. Intuitively, implicit event types are available to the application without any action by the user; and explicit event types are not available unless the user calls certains methods which are available for that purpose.

Event are also either global or per-symbol. In any event-triggering method, at most one event instance can trigger for each subtype. If an event type is global, it has only one subtype, and only one event instance of that type may trigger in a method call. If an event is per-symbol, it has one subtype for each symbol in grammar. Many instances of a per-symbol event may trigger in a method call, up to the number of symbols in the grammar.

All global event types are implicit. All explicit event types are per-symbol. The reason for event types to be explicit is to avoid the overhead of unused events, and for per-symbol event types there might be many such events.

For an event instance to trigger, its event subtype must first be declared. Subtypes of implicit events are always declared — declaring them requires no action on the part of the user. Subtypes of explicit event types must be declared by the user, using a method call provided for that purpose. Once declared, an event subtype remains declared: there is no way to remove or undo the declaration of an event subtype. Details of event declaration are provided, by event code, in the section on event codes. See Event codes.

A declared event subtype can be activated. An event instance will not trigger, unless its event subtype is activated. Subtypes of implicit event are always activated — activating them requires no action on the part of the user. Subtypes of explicit event types must be activated by the user, using a method call provided for that purpose. Implicitly activated event subtypes cannot be deactivated. Some explicitly activated event subtypes can be deactivated, using a method call available for that purpose. Details of event activation are provided, by event code, in the section on event codes. See Event codes.

When a recognizer is created, the event subtypes of a recognizer inherit their declared and activated status from the events of the base grammar. See marpa_r_new().

A Libmarpa method or macro is event-safe iff it does not change the events queue. All Libmarpa accessors are event-safe.

Regardless of the event-safety of the method calls between event triggering and event access, it is good practice to access event instances as soon as reasonable after the method that triggered them. Note that the event queue is kept in the base grammar, so that multiple recognizers using the same base grammar can overwrite each other’s events.

To find out how many events are in the event queue, use the marpa_g_event_count() method. See marpa_g_event_count().

To access specific events, use the marpa_g_event() (see marpa_g_event()) and marpa_g_event_value() (see marpa_g_event_value()) methods.