mh5queue.c File Reference

Event handling. Implementation of a combined queue for events and actions. This is the eventsystem which drives the MHEG engine. The basic implementation is as follows: Send Asynchronous Event: Add Asynchronous event to a queue. Send Synchronous Event (as a result of Executing ElementaryAction): Append Event to 'Synchronous Event Queue' Processing Loop: FOREACH Asynchronous Event DO Create 'Main Action Queue' from resulting ElementaryActions. FOREACH ElementaryAction in 'Main Action Queue' DO Execute ElementaryAction Create 'Temporary Action Queue' FOREACH Event in 'Synchronous Event Queue' DO Examine Links Append ElementaryActions to 'Temporary Action Queue' ENDFOR Prepend 'Temporary Action Queue' to 'Main Action Queue' ENDFOR ENDFOR. More...

#include <string.h>
#include "stb_os.h"
#include "mh5profile.h"
#include "mh5classes.h"
#include "mh5application.h"
#include "mh5eventtokens.h"
#include "mh5actiontokens.h"
#include "glue_memory.h"
#include "mh5object.h"
#include "mh5gate.h"
#include "glue_debug.h"
#include "mh5debug.h"
#include "mh5display.h"
#include "glue_queue.h"
#include "mh5queue.h"

Data Structures
struct	sMHEG5EventInfo
struct	s_EventQ
struct	s_SyncEventQ
struct	s_ShortSyncQ
struct	S_Element

Macros
#define	MHEG5_SYNC_UPDATE   0
#define	MAX_ACTION_LISTS   (1 << 9)
#define	ACTION_LIST_MASK   (MAX_ACTION_LISTS - 1)
#define	DO_ANY_EVENT   0x0
#define	DEFER_ASYNC_EVENTS   0x1
#define	SUSPEND_EVENTS   0x2
#define	STOP_ALL_EVENTS   0x4
#define	SYNC_Q_SIZE   128
#define	SHORT_Q_SIZE   8
#define	MAX_USER_EVENTS   2
#define	DBGPrintAction(at, t, e, p)
#define	DECLARE_RC
#define	ASSIGN_RC   (void)
#define	DBGCheckRC(t, a, p)
#define	DBGTraceEvent(lk)
#define	DBGTraceToken(lk, t, i)

Typedefs
typedef struct sMHEG5EventInfo	S_EventInfo
typedef struct s_EventQ	S_EventQueue
typedef struct s_SyncEventQ	S_SyncQueue
typedef struct s_ShortSyncQ	S_ShortSyncQ
typedef MHEG5ErrorCode(*	F_Action )(MHEG5Root *target, MHEG5GList *params)

Enumerations
enum	E_RQ_STATUS { NOTHING, EXISTS, AVAILABLE, RUNNING }

Functions
int	MHEG5InitQueues (void)
void	MHEG5stopEventsAndResetQueue (void)
	Discard any pending events and actions and prevent future events from being queued. And reset queues. See also MHEG5queueEvents. More...
void	MHEG5queueResetScene (MHEG5Root *grp)
	Reset both event queues and the action queue, discarding any pending events and actions for this scene. More...
void	MHEG5ExitQueues (void)
void	MHEG5AppendActionList (MHEG5ActionList actions)
	The supplied list of actions should execute after any already on queue. More...
void	MHEG5queueResolveTargets (MHEG5ActionList actions)
	Finds targets for the action list. More...
void	MHEG5queueUnresolveTargets (MHEG5ActionList actions)
	Clear targets for the action list. More...
void	MHEG5processQueue (void)
	Process all pending events and actions. After processing all events and actions, Normally there will not be any pending synchronous events or actions when this function is entered. The exception to this is when event processing has been disabled and re-enabled. In this case, any pending synchronous events should be processed before processing asynchronous events. More...
void	MHEG5actionListExecute (MHEG5Group *source, MHEG5ActionList act_q)
	Execute the supplied list of actions immediately. The actions will have been executed by the time the function returns. MHEG5 COR.1 specifies that certain actions are ignored when executed from OnStartUp, OnCloseDown,OnSpawnCloseDown and OnRestart attributes. More...
void	MHEG5PrependActionList (MHEG5ActionList actions)
	The supplied list of actions should execute before others on the queue. More...
void	MHEG5queueEvents (void)
	Allow future events to be stored in the event queues. See also MHEG5discardEvents. More...
void	MHEG5sendEvent (MHEG5Root *source, MHEG5EventType a_type, int data)
	Store an event in the asynchronous event queue . More...
void	MHEG5sendAppEngineEvent (E_ENGINE_EVENT engine_event)
	Store an Engine event in the asynchronous event queue. More...
void	MHEG5sendSync (MHEG5Root *source, MHEG5EventType e_type, int e_data)
	Store an event in the synchronous event queue. More...
void	MHEG5enableEventProcessing (MHEG5Bool enable)
	Enable or disable engine event processing. This function is used to implement the Call action for resident programs that normally fork by disabling engine event progressing until the program finishes. It is also used to implement the MHEG5setActiveState API function, to allow the MHEG-5 engine to be paused. More...
void	MHEG5eventProcessingReset (void)
	Causes the MHEG5enableEventProcessing counter to be reset to 0, and event processing to be enabled. This function is called when the engine is terminated to ensure that event processing will be enabled next time the engine is started. More...
void	MHEG5requestDisplayUpdate (void)
	Request display update at the end of synchronous event processing Note that this function can only be called by MHEG thread. More...

Variables
const S_Element	element_act []

Detailed Description

Event handling. Implementation of a combined queue for events and actions. This is the eventsystem which drives the MHEG engine. The basic implementation is as follows: Send Asynchronous Event: Add Asynchronous event to a queue. Send Synchronous Event (as a result of Executing ElementaryAction): Append Event to 'Synchronous Event Queue' Processing Loop: FOREACH Asynchronous Event DO Create 'Main Action Queue' from resulting ElementaryActions. FOREACH ElementaryAction in 'Main Action Queue' DO Execute ElementaryAction Create 'Temporary Action Queue' FOREACH Event in 'Synchronous Event Queue' DO Examine Links Append ElementaryActions to 'Temporary Action Queue' ENDFOR Prepend 'Temporary Action Queue' to 'Main Action Queue' ENDFOR ENDFOR.

Date

01/02/2002

Author

R.Freeman

Macro Definition Documentation

#define ACTION_LIST_MASK   (MAX_ACTION_LISTS - 1)

#define ASSIGN_RC   (void)

#define DBGCheckRC	(		t,
			a,
			p
	)

#define DBGPrintAction	(		at,
			t,
			e,
			p
	)

#define DBGTraceEvent

(

lk

)

#define DBGTraceToken	(		lk,
			t,
			i
	)

#define DECLARE_RC

#define DEFER_ASYNC_EVENTS   0x1

#define DO_ANY_EVENT   0x0

#define MAX_ACTION_LISTS   (1 << 9)

#define MAX_USER_EVENTS   2

#define MHEG5_SYNC_UPDATE   0

#define SHORT_Q_SIZE   8

#define STOP_ALL_EVENTS   0x4

#define SUSPEND_EVENTS   0x2

#define SYNC_Q_SIZE   128

Typedef Documentation

typedef MHEG5ErrorCode(* F_Action)(MHEG5Root *target, MHEG5GList *params)

typedef struct sMHEG5EventInfo S_EventInfo

typedef struct s_EventQ S_EventQueue

typedef struct s_ShortSyncQ S_ShortSyncQ

typedef struct s_SyncEventQ S_SyncQueue

Enumeration Type Documentation

enum E_RQ_STATUS

Enumerator
NOTHING
EXISTS
AVAILABLE
RUNNING

Function Documentation

void MHEG5actionListExecute	(	MHEG5Group *	source,
		MHEG5ActionList	act_q
	)

Execute the supplied list of actions immediately. The actions will have been executed by the time the function returns. MHEG5 COR.1 specifies that certain actions are ignored when executed from OnStartUp, OnCloseDown,OnSpawnCloseDown and OnRestart attributes.

Execute the supplied list of actions immediately. The actions will have been executed by the time the function returns.

Parameters

source	Source object generating the actions
actions	List of actions to execute

Returns

void

void MHEG5AppendActionList

(

MHEG5ActionList

actions

)

The supplied list of actions should execute after any already on queue.

Parameters

actions

List of actions to execute

Returns

void

void MHEG5enableEventProcessing

(

MHEG5Bool

enable

)

Enable or disable engine event processing. This function is used to implement the Call action for resident programs that normally fork by disabling engine event progressing until the program finishes. It is also used to implement the MHEG5setActiveState API function, to allow the MHEG-5 engine to be paused.

Enable or disable engine event processing. This function is used to implement the Call action for resident programs that normally fork by disabling engine event progressing until the program finishes.

Parameters

enable

MHEG5TRUE to enable event processing, MHEG5FALSE to disable event processing.

Returns

void

void MHEG5eventProcessingReset

(

void

)

Causes the MHEG5enableEventProcessing counter to be reset to 0, and event processing to be enabled. This function is called when the engine is terminated to ensure that event processing will be enabled next time the engine is started.

Returns

void

void MHEG5ExitQueues

(

void

)

int MHEG5InitQueues

(

void

)

void MHEG5PrependActionList

(

MHEG5ActionList

actions

)

The supplied list of actions should execute before others on the queue.

Execute the supplied list of actions before others.

Parameters

actions

List of actions to execute

Returns

void

void MHEG5processQueue

(

void

)

Process all pending events and actions. After processing all events and actions, Normally there will not be any pending synchronous events or actions when this function is entered. The exception to this is when event processing has been disabled and re-enabled. In this case, any pending synchronous events should be processed before processing asynchronous events.

Returns

void

void MHEG5queueEvents

(

void

)

Allow future events to be stored in the event queues. See also MHEG5discardEvents.

Allow future events to be stored in the event queues. See also MHEG5stopEventsAndQueueReset.

Returns

void

void MHEG5queueResetScene

(

MHEG5Root *

grp

)

Reset both event queues and the action queue, discarding any pending events and actions for this scene.

Returns

void

void MHEG5queueResolveTargets

(

MHEG5ActionList

actions

)

Finds targets for the action list.

Parameters

actions

List of actions to execute

Returns

void

void MHEG5queueUnresolveTargets

(

MHEG5ActionList

actions

)

Clear targets for the action list.

Parameters

actions

List of actions to execute

Returns

void

void MHEG5requestDisplayUpdate

(

void

)

Request display update at the end of synchronous event processing Note that this function can only be called by MHEG thread.

Request display update at the end of synchronous event processing.

Returns

void

void MHEG5sendAppEngineEvent

(

E_ENGINE_EVENT

engine_event

)

Store an Engine event in the asynchronous event queue.

Returns

Nothing

void MHEG5sendEvent	(	MHEG5Root *	source,
		MHEG5EventType	a_type,
		int	data
	)

Store an event in the asynchronous event queue .

Store an event in the asynchronous event queue.

Parameters

source	Source object generating the event
event	Type of event to send
data	Event data associated with this event

Returns

void

void MHEG5sendSync	(	MHEG5Root *	source,
		MHEG5EventType	e_type,
		int	e_data
	)

Store an event in the synchronous event queue.

Parameters

source	Source object generating the event
event	Type of event to send
data	Event data associated with this event

Returns

void

void MHEG5stopEventsAndResetQueue

(

void

)

Discard any pending events and actions and prevent future events from being queued. And reset queues. See also MHEG5queueEvents.

Returns

void

Variable Documentation

const S_Element element_act[]