timeline.c File Reference

This file provides the Timeline API. More...

#include "std.h"
#include <string.h>
#include "mem.h"
#include "threadapi.h"
#include "rdrapi.h"
#include "apis.h"
#include "eventapi.h"
#include "timelineapi.h"

Typedefs
typedef enum negotiation_t	negotiation_t

Enumerations
enum	negotiation_t { NEGOTIATE_OK , NEGOTIATE_OBJECTION , NEGOTIATE_WAIT }

Functions
static void	tl_mark (sw_timeline *tl, sw_tl_state state, int reason)
	Mark a timeline and all its descendants with a pending end/abort state and reason. More...
static void	orphan (sw_timeline *tl)
	Disconnect a timeline from its parent.
static void	tl_end (sw_timeline *tl, HqBool *broadcast)
	Recurse through children, then issue an Event and discard timeline. More...
static sw_tl_result	end_or_abort (sw_tl_ref ref, sw_tl_state state, int reason)
	End or Abort the Timeline. More...

Detailed Description

This file provides the Timeline API.

Copyright (C) 2023 Global Graphics Software Ltd. All rights reserved. This source code contains the confidential and trade secret information of Global Graphics Software Ltd. It may not be used, copied or distributed for any reason except as set forth in the applicable Global Graphics license agreement.

The Timeline API is used to manage, communicate and negotiate the lifespan of entities; arrange timelines into hierarchies; report state, progress along and extent of timelines; and attribute textual feedback and error messages to timeline hierarchies.

It makes extensive use of the Event system and is independent of the core.

Typedef Documentation

negotiation_t

typedef enum negotiation_t negotiation_t

Return values from timeline extension negotiation.

Enumeration Type Documentation

negotiation_t

enum negotiation_t

Return values from timeline extension negotiation.

Enumerator
NEGOTIATE_OK	Allowed timeline to end/abort.
NEGOTIATE_OBJECTION	Objection from event sustained.
NEGOTIATE_WAIT	Negotiation blocked.

Function Documentation

end_or_abort()

static sw_tl_result end_or_abort ( sw_tl_ref  ref, sw_tl_state  state, int  reason  )

static

End or Abort the Timeline.

First child priorities are checked, as high priority children prolong the parent. Then a negotiation takes place comprising a number of Events. If this fails, the Timeline prolongs. Otherwise the Timeline and children are marked as dead to prevent new children being added, then all children and finally this Timeline are ended, issuing Events as they go.

Parameters

ref	The Timeline to end
state	Either TL_STATE_END or TL_STATE_ABORT
reason	The reason for the TL_STATE_ABORT

Returns

SW_TL_SUCCESS if the Timeline ends. SW_TL_ERROR_IN_USE if the Timeline prolongs. SW_TL_ERROR_UNKNOWN if the Timeline cannot be found. SW_TL_ERROR_SYNTAX if an event handler called during timeline negotiation or takedown attempts to end or abort a timeline already involved in the negotiation or takedown, potentially causing a deadlock. This is a programming error, and will also cause an assert.

tl_end()

static void tl_end ( sw_timeline *  tl, HqBool *  broadcast  )

static

Recurse through children, then issue an Event and discard timeline.

As Events are issued throughout this process, all the Timelines that are about to be discarded must have had their states changed to dead already, so any Handlers called can't do crazy things. Note that many harmless actions are allowed anyway, because we're lenient.

On entry the mutex is held, but the Timeline in question is not locked.

tl_mark()

static void tl_mark ( sw_timeline *  tl, sw_tl_state  state, int  reason  )

static

Mark a timeline and all its descendants with a pending end/abort state and reason.

This is necessary because Events are issued while the Timelines are being discarded, so we musn't allow any new children to be added into this part of the hierarchy.

We may be competing with other threads to mark parts of the hierarchy, so don't overwrite the pending end/abort state and reason set by another thread. This thread may take over issuing the event for that thread's marks, however.