<h1><aclass="back"title="Return to index"href="index.html#events">Event-driven programming</a></h1>
<p>
The addition of event-driven programming capacities to the Logtalk system is based on a simple but powerful idea <ahref="../bibliography.html#Moura94">[Moura 94]</a>:
</p>
<blockquote>
<p>
The computations must result, not only from message sending, but also from the <strong>observation</strong> of message sending.
</p>
</blockquote>
<p>
The need to associate computations to the occurrence of events was very early recognized in several knowledge representation languages, in some programming languages <ahref="../bibliography.html#Stefik86">[Stefik 86</a>, <ahref="../bibliography.html#Moon86">Moon 86]</a>, and in the implementation of operative systems <ahref="../bibliography.html#Tanenbaum87">[Tanenbaum 87]</a> and graphical user interfaces.
</p>
<p>
With the integration between object-oriented and event-driven programming, we intend to achieve the following goals:
</p>
<ul>
<li>Minimize the coupling between objects. An object should only contain what is intrinsic to it. If an object observes another object, that means that it should depend only on the (public) protocol of the object observed, and not on the implementation of that same protocol.</li>
</ul>
<ul>
<li>Provide a framework for building reflexive systems in Logtalk based on the dynamic behaviour of objects in complement to the reflective information of the object's contents and relations.</li>
</ul>
<hr/>
<h2><aclass="back"title="Return to index"name="definitions"href="index.html#events_definitions">Definitions</a></h2>
<p>
The words <em>event</em> and <em>monitor</em> have multiple meanings in computer science, so, to avoid misunderstandings, it is advisable that we start by defining them in the Logtalk context.
</p>
<h3><aclass="back"title="Return to index"name="event"href="index.html#events_event">Event</a></h3>
<p>
In an object-oriented system, all computations start through message sending. It thus becomes quite natural to declare that the only event that can occur in this kind of system is precisely the sending of a message. An event can thus be represented by the ordered tuple <code>(Object, Message, Sender)</code>.
</p>
<p>
If we consider message processing an indivisible activity, we can interpret the sending of a message and the return of the control to the object that has sent the message as two distinct events. This distinction allows us to have a more precise control over a system dynamics. In Logtalk, these two types of events have been named <code>before</code> and <code>after</code>, respectively for message sending and returning. Therefore, we end up by representing an event by the ordered tuple <code>(Event, Object, Message, Sender)</code>.
</p>
<p>
The implementation of the event notion in Logtalk enjoys the following properties:
</p>
<h4>Independence between the two types of events</h4>
<blockquote>
<p>
We can choose to watch only one event type or to process each one of the events associated to a message sending in an independent way.
</p>
</blockquote>
<h4>All events are automatically generated by the message sending mechanism</h4>
<blockquote>
<p>
The task of generating events is accomplished, in a transparent way, by the message sending mechanism. The user just defines which are the events in which he is interested in.
</p>
</blockquote>
<h4>The events watched at any moment can be dynamically changed during program execution</h4>
<blockquote>
<p>
The notion of event allows the user not only to have the possibility of observing, but also of controlling and modifying an application behaviour, namely by dynamically changing the observed events during program execution. It is our goal to provide the user with the possibility of modeling the largest possible number of situations.
</p>
</blockquote>
<h3><aclass="back"title="Return to index"name="monitor"href="index.html#events_monitor">Monitor</a></h3>
<p>
Complementary to the notion of event is the notion of monitor. A monitor is an object that is automatically notified by the message sending mechanisms whenever certain events occur. A monitor should naturally define the actions to be carried out whenever a monitored event occurs.
</p>
<p>
The implementation of the monitor notion in Logtalk enjoys the following properties:
</p>
<h4>Any object can act as a monitor</h4>
<blockquote>
<p>
The monitor status is a role that any object can perform during its existence. The minimum protocol necessary is declared in protocol <code>event_handlersp</code>. An extended protocol is available in protocol <code>monitorp</code>.
</p>
</blockquote>
<h4>Unlimited number of monitors for each event</h4>
<blockquote>
<p>
Several monitors can observe the same event because of distinct reasons. Therefore, the number of monitors per event is bounded only by the available computing resources.
</p>
</blockquote>
<h4>The monitor status of an object can be dynamically changed in runtime</h4>
<blockquote>
<p>
This property does not imply that an object must be dynamic to act as a monitor (the monitor status of an object is not stored in the object).
</p>
</blockquote>
<h4>The execution of actions, defined in a monitor, associated to each event, never affects the term that denotes the message involved</h4>
<blockquote>
<p>
In other words, if the message contains uninstantiated variables, these are not affected by the acting of monitors associated to the event.
</p>
</blockquote>
<hr/>
<h2><aclass="back"title="Return to index"name="generation"href="index.html#events_generation">Event generation</a></h2>
<p>
For each message that is sent (using the <atitle="Consult reference manual"href="../refman/control/to_object2.html"><code>::/2</code></a> message sending mechanism) the runtime system automatically generates two events. The first - <code>before event</code> - is generated when the message is sent. The second - <code>after event</code> - is generated after the message has successfully been executed.
</p>
<hr/>
<h2><aclass="back"title="Return to index"name="communicating"href="index.html#events_communicating">Communicating events to monitors</a></h2>
<p>
Whenever a spied event occurs, the message sending mechanisms call the corresponding event handlers directly for all registered monitors. These calls are made bypassing the message sending primitives in order to avoid potential endless loops. The event handlers consist in user definitions for pre-declared public predicates (one for each event kind; see below for more details).
</p>
<hr/>
<h2><aclass="back"title="Return to index"name="performance"href="index.html#events_performance">Performance concerns</a></h2>
<p>
The existence of monitored messages should not affect the processing of the remaining messages. On the other hand, for each message that has been sent, the system must verify if its respective event is monitored. This verification clearly must be ideally performed in constant time and independently from the number of monitored events. The events representation takes advantage of the first argument indexing performed by most Prolog compilers, which ensure - in the general case - an access in constant time.
</p>
<hr/>
<h2><aclass="back"title="Return to index"name="semantics"href="index.html#events_semantics">Monitor semantics</a></h2>
<p>
The established semantics for monitors actions consists on considering its success as a necessary condition so that a message can succeed:
<li>All actions associated to events of type <code>after</code> also have to succeed so that the message itself succeeds. The failure of any action associated to an event of type <code>after</code> forces backtracking over the message execution (the failure of a monitor never causes backtracking over the preceding monitor actions).</li>
Note that this is the most general choice. If we wish a transparent presence of monitors in a message processing, we just have to define the monitor actions in such a way that they never fail (which is very simple to accomplish).
</p>
<hr/>
<h2><aclass="back"title="Return to index"name="order"href="index.html#events_order">Activation order of monitors</a></h2>
<p>
Ideally, whenever there are several monitors defined for the same event, the calling order should not interfere with the result. However, this is not always possible. In the case of an event of type <code>before</code>, the failure of a monitor prevents a message from being sent and prevents the execution of the remaining monitors. In case of an event of type <code>after</code>, a monitor failure will force backtracking over message execution. Different orders of monitor activation can therefore lead to different results if the monitor actions imply object modifications unrecoverable in case of backtracking. Therefore, the order for monitor activation must be always taken as arbitrary. In effect, to suppose or to try to impose a specific sequence implies a global knowledge of an application dynamics, which is not always possible. Furthermore, that knowledge can reveal itself as incorrect if there is any changing in the execution conditions. Note that, given the independence between monitors, it does not make sense that a failure forces backtracking over the actions previously executed.
</p>
<hr/>
<h2><aclass="back"title="Return to index"name="events"href="index.html#events_handling">Event handling</a></h2>
<p>
Logtalk provides three built-in predicates for event handling. These predicates enable you to find what events are defined, to define new events and to abolish events when they are no longer needed. If you plan to use events extensively in your application, then you should probably define a set of objects that use the built-in predicates described below to implement more sophisticated and high-level behaviour.
</p>
<h3><aclass="back"title="Return to index"name="finding"href="index.html#events_finding">Finding defined events</a></h3>
<p>
The events that are currently defined can be retrieved using the Logtalk built-in predicate <atitle="Consult reference manual"href="../refman/builtins/current_event5.html"><code>current_event/5</code></a>:
Note that this predicate will return a <strong>set</strong> of matching events if some of the returned arguments are free variables or contain free variables.
</p>
<h3><aclass="back"title="Return to index"name="defining"href="index.html#events_defining">Defining new events</a></h3>
<p>
New events can be defined using the Logtalk built-in predicate <atitle="Consult reference manual"href="../refman/builtins/define_events5.html"><code>define_events/5</code></a>:
Note that if any of the arguments is a free variable or contains free variables, this call will define the <strong>set</strong> of matching events.
</p>
<h3><aclass="back"title="Return to index"name="abolishing"href="index.html#events_abolishing">Abolishing defined events</a></h3>
<p>
Events that are no longer needed may be abolished using the <atitle="Consult reference manual"href="../refman/builtins/abolish_events5.html"><code>abolish_events/5</code></a> built-in predicate:
If called with free variables, this goal will remove all matching events.
</p>
<h3><aclass="back"title="Return to index"name="handlers"href="index.html#events_handlers">Defining event handlers</a></h3>
<p>
There are two pre-declared public predicates, <atitle="Consult reference manual"href="../refman/methods/before3.html"><code>before/3</code></a> and <atitle="Consult reference manual"href="../refman/methods/after3.html"><code>after/3</code></a>, that are automatically called to handle <code>before</code> and <code>after</code> events. Any object that plays the role of monitor should define one or both of these event handler methods:
</p>
<pre>
before(Object, Message, Sender) :-
... .
after(Object, Message, Sender) :-
... .
</pre>
<p>
The arguments in both methods are instantiated by the message sending mechanisms when a spied event occurs. For example, assume that we want to define a monitor called <code>tracer</code> that will track any message sent to an object by printing a describing text to the standard output. Its definition could be something like:</p>
After compiling and loading both objects, we can start tracing every message sent to any object by calling the <code>define_events/5</code> built-in predicate:
</p>
<pre>
| ?- define_events(_, _, _, _, tracer).
yes
</pre>
<p>
From now on, every message sent to any object will be traced to the standard output stream:
</p>
<pre>
| ?- any::bar(X).
call: any <-- bar(X) from user
exit: any <-- bar(bar) from user
X = bar
yes
</pre>
<p>
To stop tracing, we can use the <code>abolish_events/5</code> built-in predicate:
