Meta::MMLEntity Class Reference

The central actor base class in an MML program. More...

#include <MMLEntity.h>

Inheritance diagram for Meta::MMLEntity:

Public Member Functions
	MMLEntity ()
	MMLEntity (int id)
	MMLEntity (const MMLEntity &entity, bool recursive=false)
	MMLEntity (const mvar &v, RestoreOpt opt)
virtual	~MMLEntity ()
virtual void	store (mvar &v) const
virtual void	store (mvar &v, bool recursive) const
virtual MObject *	clone () const
virtual mnode	process (mnode n, uint32_t flags=0)
virtual bool	instanceOf (ClassIdType classId) const
virtual void	assignId ()
virtual void	releaseId ()
virtual mvar	init ()
void	setId (int id)
int	id () const
void	setTag (const mvar &tag)
const mvar &	tag () const
virtual mstr	name () const
bool	isThreaded () const
void	setThreaded (bool flag)
virtual MMessageBuffer *	initPrivateBuffer ()
virtual MMessageBuffer *	initSharedBuffer ()
MMessageBuffer *	privateBuffer () const
MMessageBuffer *	sharedBuffer () const
void	connect (MMLEntity *ent, const mvar &data=undef, const mstr &edgeTag="")
void	connect (const mvar &ent, const mvar &data=undef, const mstr &edgeTag="")
virtual void	onConnect (MMLEntity *ent, const mstr &edgeTag)
void	disconnect (MMLEntity *ent, const mstr &edgeTag)
void	disconnect (const mvar &ent, const mstr &edgeTag)
void	disconnect (MMLEntity *ent)
void	disconnect (const mvar &ent)
void	disconnect ()
virtual void	onDisconnect (MMLEntity *ent, const mstr &edgeTag)
const mvar &	edgeData (const MMLEntity *ent, const mstr &edgeTag="") const
const mvar &	edgeData (const mvar &ent, const mstr &edgeTag="") const
virtual void	onAttach (MMLEntity *ent, const mstr &edgeTag)
void	detach ()
virtual void	onDetach (MMLEntity *ent, const mstr &edgeTag)
void	signal (MMLEntity *ent, const mstr &edgeTag="")
void	signal (const mvar &ent, const mstr &edgeTag="")
void	signal (MMLEntity *ent, const mvar &v, const mstr &edgeTag)
void	signal (const mvar &ent, const mvar &v, const mstr &edgeTag)
void	signalAll ()
void	signalAll (const mvar &v)
size_t	outEdgeCount () const
size_t	inEdgeCount () const
void	outEdges (mvec &ents, mvec &edgeTags) const
void	outEdges (mvec &ents) const
mvec	outEdges () const
void	setActive (bool flag)
bool	isActive () const
void	queue ()
void	queue (MProcTask task, MProc::SignalMap signalMap=0, double priority=0, const mtime *time=0)
virtual mvar	run ()
void	setRunAll (bool flag)
bool	runAll () const
bool	isRunCycle () const
virtual mvar	endRun ()
const mvar &	state () const
void	setKept (bool kept)
bool	isKept () const
void	query (mnode func, mvec &results, bool recursive, bool self, bool error) const
mvar	query (mnode func, bool recursive=false, bool self=true, bool error=true) const
void	execute (mnode func, bool recursive=false, bool self=true, bool error=true) const
void	find (const mstr &name, mvec &results, bool recursive, bool self) const
mvar	find (const mstr &name, bool recursive=false, bool self=true) const
void	await ()
bool	await (const mtime &timeout)
void	handleEvents ()
virtual mvar	handleEvent (const mvar &evt)
void	send (MMLEntity *ent, const mvar &evt, const mnum &delay)
void	send (const mvar &ent, const mvar &evt, const mnum &delay)
void	send (MMLEntity *ent, const mvar &evt)
void	send (const mvar &ent, const mvar &evt)
void	relay (const mvar &evt, const mnum &delay)
void	relay (const mvar &evt)
void	post (MMLEntity *ent, const mvar &evt, const mnum &delay)
void	post (const mvar &ent, const mvar &evt, const mnum &delay)
void	post (MMLEntity *ent, const mvar &evt)
void	post (const mvar &ent, const mvar &evt)
void	log (const mvar &msg, bool concise=true) const
void	listen (MMLEntity *ent)
void	listen (const mvar &ent)
virtual mvar	end ()
mvar	getLinks (mnode f=mfunc("List"))
Static Public Member Functions
static MMLEntity *	ptr (const mvar &v, bool dynamic=false)
static mvar	time ()
static mvar	interval ()
Static Public Attributes
static const ClassIdType	ClassId
Friends
class	MMLEntity_

Detailed Description

The central actor base class in an MML program.

MML entities form the basis of an MML program, providing abstractions which facilitate modeling and simulation: event communication and handling, graph-based chaining and signalling for concurrent execution (using MProc), synchronization methods, time management, recursive querying/execution, and more. MML entities and the "networks" formed by their interconnections are fully storeable and restoreable.

Constructor & Destructor Documentation

Meta::MMLEntity::MMLEntity ( )

Constructor.

Meta::MMLEntity::MMLEntity ( int id )

Constructor.

In most cases this variant of the constructor is not needed -- it is primarily used for store/restore.

Meta::MMLEntity::MMLEntity	(	const MMLEntity &	entity,
		bool	recursive = `false`
	)

Copy constructor.

Parameters:

recursive

If true, recursively copy all connected entities.

Meta::MMLEntity::MMLEntity	(	const mvar &	v,
		RestoreOpt	opt
	)

Restore constructor.

virtual Meta::MMLEntity::~MMLEntity ( ) [virtual]

Destructor.

Member Function Documentation

virtual void Meta::MMLEntity::assignId ( ) [virtual]

Called when this entity needs to have an id assigned to it. Should not be re-implemented under normal circumstances.

bool Meta::MMLEntity::await ( const mtime & timeout )

Block until after completion of this entity's next run or until timeout is reached.

Returns:: true on success, i.e: did not time out.

void Meta::MMLEntity::await ( )

Block until after completion of this entity's next run.

virtual MObject* Meta::MMLEntity::clone ( ) const [virtual]

Returns:: A copy of this entity (non-recursive).

Reimplemented from Meta::MObject.

void Meta::MMLEntity::connect	(	const mvar &	ent,
		const mvar &	data = `undef`,
		const mstr &	edgeTag = `""`
	)

Form an outward connection to ent.

Parameters:

	ent	The entity to connect to.
	data	The edge data to attach to this edge.
	edgeTag	The edge tag

void Meta::MMLEntity::connect	(	MMLEntity *	ent,
		const mvar &	data = `undef`,
		const mstr &	edgeTag = `""`
	)

Form an outward connection to ent.

Parameters:

	ent	The entity to connect to.
	data	The edge data to attach to this edge.
	edgeTag	The edge tag

void Meta::MMLEntity::detach ( )

Detach all inward connections.

void Meta::MMLEntity::disconnect ( )

Disconnect all outward connections.

void Meta::MMLEntity::disconnect ( const mvar & ent )

Disconnect all outward connections to ent.

void Meta::MMLEntity::disconnect ( MMLEntity * ent )

Disconnect all outward connections to ent.

void Meta::MMLEntity::disconnect	(	const mvar &	ent,
		const mstr &	edgeTag
	)

Disconnect outward connection to ent referred to by edgeTag.

void Meta::MMLEntity::disconnect	(	MMLEntity *	ent,
		const mstr &	edgeTag
	)

Disconnect outward connection to ent referred to by edgeTag.

const mvar& Meta::MMLEntity::edgeData	(	const mvar &	ent,
		const mstr &	edgeTag = `""`
	)			const

Returns:: The edge data associated with the outward connection to ent.

const mvar& Meta::MMLEntity::edgeData	(	const MMLEntity *	ent,
		const mstr &	edgeTag = `""`
	)			const

Returns:: The edge data associated with the outward connection to ent.

virtual mvar Meta::MMLEntity::end ( ) [virtual]

An application-specific method that is called when this entity is reclaimed by root.

virtual mvar Meta::MMLEntity::endRun ( ) [virtual]

Application-specific method called after run() completes and events have been handled.

Reimplemented in Meta::MMLRoot.

void Meta::MMLEntity::execute	(	mnode	func,
		bool	recursive = `false`,
		bool	self = `true`,
		bool	error = `true`
	)			const

Similar to query(), execute a function (recursively) on all outward connections but do not gather the results.

Parameters:

	func	The function to run on each entity.
	recursive	If true, run query recursively.
	self	true if query should be run on self.
	error	false if MProcessError's should be suppressed.

mvar Meta::MMLEntity::find	(	const mstr &	name,
		bool	recursive = `false`,
		bool	self = `true`
	)			const

A common type of query(), (recursively) find all outward connections matching a name.

Parameters:

	name	The name to match.
	recursive	If true, run query recursively.
	self	true if find should include self.

Returns:: Results of search as an mvar vector. The mvar head is set to the first entity found.

void Meta::MMLEntity::find	(	const mstr &	name,
		mvec &	results,
		bool	recursive,
		bool	self
	)			const

A common type of query(), (recursively) find all outward connections whose name() matches name.

Parameters:

	name	The name to match.
	results	On exit, the results on the search.
	recursive	If true, run query recursively.
	self	true if find should include self.

mvar Meta::MMLEntity::getLinks ( mnode f = mfunc("List") )

Get links in M format.

Parameters:

f

On output, the links in M format as the specified sequence.

Returns:: The links as an mvar.

virtual mvar Meta::MMLEntity::handleEvent ( const mvar & evt ) [virtual]

Application-specific event handler. Re-implement to determine how this entity responds to events.

Reimplemented in Meta::MMLGraphScene, Meta::MMLGridScene, Meta::MMLRobotScene, Meta::MMLScene, Meta::MMLSceneBase, and Meta::MMLSpaceScene.

void Meta::MMLEntity::handleEvents ( )

Explicitly handle events. Usually this is called at some point in run(). However, it is done implicitly after run() if omitted.

int Meta::MMLEntity::id ( ) const

Get this entity's id.

size_t Meta::MMLEntity::inEdgeCount ( ) const

Returns:: The number of inward connections.

virtual mvar Meta::MMLEntity::init ( ) [virtual]

Application-specific initialization function.

virtual MMessageBuffer* Meta::MMLEntity::initPrivateBuffer ( ) [virtual]

Returns:: A message buffer to be used for events directly solely to this entity.

virtual MMessageBuffer* Meta::MMLEntity::initSharedBuffer ( ) [virtual]

Returns:: A message buffer to be used for events communicated to outwardly connected entities.

virtual bool Meta::MMLEntity::instanceOf ( ClassIdType classId ) const [virtual]

Returns:: true if this is an instance of a specified classId.

Reimplemented from Meta::MObject.

static mvar Meta::MMLEntity::interval ( ) [static]

Returns:: Run cycle interval.

bool Meta::MMLEntity::isActive ( ) const

Returns:: Whether or not this entity may be activated.

bool Meta::MMLEntity::isKept ( ) const

Set whether this entity is reclaimed by root.

bool Meta::MMLEntity::isRunCycle ( ) const

Returns:: true if run() was invoked by a run cycle interval.

bool Meta::MMLEntity::isThreaded ( ) const

Returns:: true if this entity may use threaded execution.

void Meta::MMLEntity::listen ( const mvar & ent )

Subscribe to the specified entity's shared buffer.

void Meta::MMLEntity::listen ( MMLEntity * ent )

Subscribe to the specified entity's shared buffer.

void Meta::MMLEntity::log	(	const mvar &	msg,
		bool	concise = `true`
	)			const

Logs entity time, name, and message. Ensures that output does not get interleaved when multiple threads log simultaneously.

Parameters:

	msg	Message to display.
	concise	Whether to use concise numerics.

virtual mstr Meta::MMLEntity::name ( ) const [virtual]

The name of the entity used for such things as logging, or queries, e.g: find(). By default name is the entity's tag converted to a string.

virtual void Meta::MMLEntity::onAttach	(	MMLEntity *	ent,
		const mstr &	edgeTag
	)			`[virtual]`

Called when forming an outward connection.

Parameters:

ent

The entity this entity is attaching to.

virtual void Meta::MMLEntity::onConnect	(	MMLEntity *	ent,
		const mstr &	edgeTag
	)			`[virtual]`

Called when forming an outward connection.

Parameters:

ent

The entity connected.

virtual void Meta::MMLEntity::onDetach	(	MMLEntity *	ent,
		const mstr &	edgeTag
	)			`[virtual]`

Called when severing an inward connection.

Parameters:

ent

The entity this entity is detaching from.

virtual void Meta::MMLEntity::onDisconnect	(	MMLEntity *	ent,
		const mstr &	edgeTag
	)			`[virtual]`

Called when severing an outward connection.

Parameters:

ent

The entity disconnected.

size_t Meta::MMLEntity::outEdgeCount ( ) const

Returns:: The number of outward connections.

mvec Meta::MMLEntity::outEdges ( ) const

Return a vector containing the entities of all outward connections. The ents vector contains one entity for each edge even though there may exist multiple edges to that entity.

void Meta::MMLEntity::outEdges ( mvec & ents ) const

Get a vector containing the entities of all outward connections. The ents vector contains one entity for each edge even though there may exist multiple edges to that entity.

void Meta::MMLEntity::outEdges	(	mvec &	ents,
		mvec &	edgeTags
	)			const

Get a vector containing the entities and edge tags all outward connections.

void Meta::MMLEntity::post	(	const mvar &	ent,
		const mvar &	evt
	)

Send an event to the target entity's shared buffer. The delay is the current MML time advance rate (interval).

Parameters:

	ent	Target entity.
	evt	The event to send.

void Meta::MMLEntity::post	(	MMLEntity *	ent,
		const mvar &	evt
	)

Send an event to the target entity's shared buffer. The delay is the current MML time advance rate (interval).

Parameters:

	ent	Target entity.
	evt	The event to send.

void Meta::MMLEntity::post	(	const mvar &	ent,
		const mvar &	evt,
		const mnum &	delay
	)

Send an event to the target entity's shared buffer.

Parameters:

	ent	Target entity.
	evt	The event to send.
	delay	Delivery time delay.

void Meta::MMLEntity::post	(	MMLEntity *	ent,
		const mvar &	evt,
		const mnum &	delay
	)

Send an event to the target entity's shared buffer.

Parameters:

	ent	Target entity.
	evt	The event to send.
	delay	Delivery time delay.

MMessageBuffer* Meta::MMLEntity::privateBuffer ( ) const

Returns:: The message buffer used for events directly solely to this entity.

virtual mnode Meta::MMLEntity::process	(	mnode	n,
		uint32_t	flags = `0`
	)			`[virtual]`

Process method.

Reimplemented from Meta::MObject.

Reimplemented in Meta::MMLGraphScene, Meta::MMLGrid, Meta::MMLGridScene, Meta::MMLRobotScene, Meta::MMLRoot, Meta::MMLScene, Meta::MMLSceneBase, Meta::MMLSharedVar, and Meta::MMLSpaceScene.

static MMLEntity* Meta::MMLEntity::ptr	(	const mvar &	v,
		bool	dynamic = `false`
	)			`[static]`

Convenience method to perform a cast on v to MMLEntity.

Parameters:

dynamic

If true perform a dynamic cast and ensure type is MMLEntity.

Returns:: Pointer to successfully casted entity or null in case of failure.

Reimplemented in Meta::MMLRoot.

mvar Meta::MMLEntity::query	(	mnode	func,
		bool	recursive = `false`,
		bool	self = `true`,
		bool	error = `true`
	)			const

Execute a query (recursively) on all outward connections and gather the results.

Parameters:

	func	The function to run on each entity.
	recursive	If true, run query recursively.
	self	true if query should be run on self.
	error	false if MProcessError's should be suppressed.

Returns:: An mvar containing a vector of the results of the query.

void Meta::MMLEntity::query	(	mnode	func,
		mvec &	results,
		bool	recursive,
		bool	self,
		bool	error
	)			const

Execute a query (recursively) on all outward connections and gather the results.

Parameters:

	func	The function to run on each entity.
	results	On completion, a vector of the results of the query.
	recursive	If true, run query recursively.
	self	true if query should be run on self.
	error	false if MProcessError's should be suppressed.

void Meta::MMLEntity::queue	(	MProcTask *	task,
		MProc::SignalMap *	signalMap = `0`,
		double	priority = `0`,
		const mtime *	time = `0`
	)

Queue the entity for execution using MProc::queue() parameters.

void Meta::MMLEntity::queue ( )

Queue the entity for execution. Normally this is only called once on the top-level entity.

void Meta::MMLEntity::relay ( const mvar & evt )

Relay an event to this entity's shared buffer. The delay is the current MML time advance rate (interval).

Parameters:

evt

The event to send.

void Meta::MMLEntity::relay	(	const mvar &	evt,
		const mnum &	delay
	)

Relay an event to this entity's shared buffer.

Parameters:

	evt	The event to send.
	delay	Delivery time delay.

virtual void Meta::MMLEntity::releaseId ( ) [virtual]

Called upon entity destruction to release its id. Should not be re-implemented under normal circumstances.

virtual mvar Meta::MMLEntity::run ( ) [virtual]

Application-specific run method.

Returns:: Entity "state". Normally state is unused and an entity simply returns 0.

Reimplemented in Meta::MMLGraphScene, Meta::MMLGrid, Meta::MMLGridScene, Meta::MMLRobotScene, Meta::MMLScene, and Meta::MMLSpaceScene.

bool Meta::MMLEntity::runAll ( ) const

Return the flag that specifies if this entity's run() method called all the time as opposed to only during a run cycle interval.

void Meta::MMLEntity::send	(	const mvar &	ent,
		const mvar &	evt
	)

Send an event to a specific entity. The event gets posted in the target entity's private buffer. The delay is the current MML time advance rate (interval).

Parameters:

	ent	The target entity.
	evt	The event to send.

void Meta::MMLEntity::send	(	MMLEntity *	ent,
		const mvar &	evt
	)

Send an event to a specific entity. The event gets posted in the target entity's private buffer. The delay is the current MML time advance rate.

Parameters:

	ent	The target entity.
	evt	The event to send.

void Meta::MMLEntity::send	(	const mvar &	ent,
		const mvar &	evt,
		const mnum &	delay
	)

Send an event to a specific entity. The event gets posted in the target entity's private buffer.

Parameters:

	ent	The target entity.
	evt	The event to send.
	delay	Delivery time delay.

void Meta::MMLEntity::send	(	MMLEntity *	ent,
		const mvar &	evt,
		const mnum &	delay
	)

Send an event to a specific entity. The event gets posted in the target entity's private buffer.

Parameters:

	ent	The target entity.
	evt	The event to send.
	delay	Delivery time delay.

void Meta::MMLEntity::setActive ( bool flag )

Set whether or not this entity may be activated.

void Meta::MMLEntity::setId ( int id )

Explicitly set this entity's id.

void Meta::MMLEntity::setKept ( bool kept )

Set whether this entity is reclaimed by root. Normally an entity is reclaimed when it has no inward connections. The default is true.

void Meta::MMLEntity::setRunAll ( bool flag )

Set flag to true to have this entity's run() method called all the time as opposed to only during a run cycle interval. Default is false.

void Meta::MMLEntity::setTag ( const mvar & tag )

Set tag data. By default, an entity's tag is its id.

void Meta::MMLEntity::setThreaded ( bool flag )

Set whether this entity potentially uses threaded execution. This is needed because some operations, such as GUI calls, must run on the main thread.

MMessageBuffer* Meta::MMLEntity::sharedBuffer ( ) const

Returns:: The message buffer used for events communicated to outwardly connected entities.

void Meta::MMLEntity::signal	(	const mvar &	ent,
		const mvar &	v,
		const mstr &	edgeTag
	)

Signal an outward connection by entity. The signal gets value v.

void Meta::MMLEntity::signal	(	MMLEntity *	ent,
		const mvar &	v,
		const mstr &	edgeTag
	)

Signal an outward connection by entity. The signal gets value v.

void Meta::MMLEntity::signal	(	const mvar &	ent,
		const mstr &	edgeTag = `""`
	)

Signal an outward connection by entity. The signal gets the value of its edge data.

void Meta::MMLEntity::signal	(	MMLEntity *	ent,
		const mstr &	edgeTag = `""`
	)

Signal an outward connection by entity. The signal gets value of its edge data.

void Meta::MMLEntity::signalAll ( const mvar & v )

Signal all outward connections with value v.

void Meta::MMLEntity::signalAll ( )

Signal all outward connections.

const mvar& Meta::MMLEntity::state ( ) const

Returns:: The entity state which was set by last time run() was called.

virtual void Meta::MMLEntity::store	(	mvar &	v,
		bool	recursive
	)			const `[virtual]`

Store this entity to v.

Parameters:

recursive

If true, recursively store all connected entities.

virtual void Meta::MMLEntity::store ( mvar & v ) const [virtual]

Store this entity to v.

Reimplemented from Meta::MObject.

Reimplemented in Meta::MMLRoot.

const mvar& Meta::MMLEntity::tag ( ) const

Get tag data.

static mvar Meta::MMLEntity::time ( ) [static]

Returns:: Global MML time.

The documentation for this class was generated from the following file:

AndroMeta/include/Meta/MMLEntity.h

Meta::MMLEntity Class Reference

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation