(v13) Timeline priority

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP

A timeline represents something that has a finite lifetime and when you create a timeline an event is issued. You can do various things with the timeline, and then when you end the timeline another event is issued to say that it has ended. However, because we have a hierarchy it is possible that other parties have created timelines that are connected to

this timeline; children of this timeline. When a timeline is ended the children of that timeline may either continue or end according to the priority given to the timeline when it is created. If a child of a timeline has the same or higher priority as its parent, ending the parent timeline may not cause it to end yet, it may automatically be prolonged until its child has ended.

However, if the child is a lower priority, ending the parent timeline will automatically end the child timeline.

Assuming there are no other the same or higher priority children that are going to prolong the parent timeline, the next thing that happens is that the timeline system issues an event called “ending” (TL_STATE_ENDING) which allows other systems to object to the timeline ending and possibly to prolong it. This means that, in effect, any entity that has a timeline that represents its lifetime automatically gains a method by which a negotiation can take place about whether that entity is finished with it or not.

The default behavior for timelines is to disallow children to prolong a parent timeline. This is the normal case when the lifetime of the timeline represents the scope of an object, which will be destroyed at the end of that scope regardless of any objections. In this normal case, even if handlers object to ending the timeline, or if child timelines are attached with a higher priority, the timeline will end. The ending event will be sent to the handlers first, followed by an ended event.

Timelines may be started with optional behavior specified. Amongst the options supported is an option to prolong the timeline, in which case the timeline can be extended by a higher-priority child or a handler objecting, as described above. A timeline with a dynamic scope (one that can be prolonged) can be created as a child of a timeline with a static scope, but not the other way around. An error will be returned if an attempt is made to create a static timeline as a child of a dynamic timeline.