#include <model.h>

Inheritance diagram for fpmas::api::model::AgentGroup:

[legend]

Public Types
enum	Event { INSERT , ERASE , ADD , REMOVE }

Public Member Functions
virtual GroupId	groupId () const =0

virtual const Behavior &	behavior ()=0

virtual void	add (Agent *agent)=0

virtual void	remove (Agent *agent)=0

virtual void	clear ()=0

virtual void	insert (AgentPtr *agent)=0

virtual void	erase (AgentPtr *agent)=0

virtual std::vector< Agent * >	agents () const =0

virtual std::vector< Agent * >	localAgents () const =0

virtual std::vector< Agent * >	distantAgents () const =0

virtual api::scheduler::Job &	job ()=0

virtual const api::scheduler::Job &	job () const =0

virtual api::scheduler::Job &	agentExecutionJob ()=0

virtual const api::scheduler::Job &	agentExecutionJob () const =0

virtual api::scheduler::JobList	jobs () const =0

virtual void	addEventHandler (Event event, api::utils::Callback< Agent * > *callback)=0

virtual void	removeEventHandler (Event event, api::utils::Callback< Agent * > *callback)=0

Detailed Description

AgentGroup API.

An AgentGroup describes a group of Agents that can be executed independently in any order, potentially in parallel.

More precisely, the AgentGroup is associated to an api::scheduler::Job that contains all the tasks corresponding to Agents added in the group.

The AgentGroup's Job can then be scheduled thanks to the api::scheduler::Scheduler API to define when the AgentGroup should be executed.

A Model can be used to conveniently build AgentGroups.

Member Enumeration Documentation

◆ Event

enum fpmas::api::model::AgentGroup::Event

Events that can be emitted by the AgentGroup interface.

Enumerator
INSERT	Sent after a node has been inserted in the AgentGroup.
ERASE	Sent before an Agent is erased from the AgentGroup.
ADD	Sent after a node has been added to the AgentGroup.
REMOVE	Sent before an Agent is removed from the AgentGroup.

Member Function Documentation

◆ groupId()

virtual GroupId fpmas::api::model::AgentGroup::groupId ( ) const

pure virtual

Returns the ID of this group.

Returns: group id

Implemented in fpmas::model::detail::AgentGroupBase.

◆ behavior()

virtual const Behavior & fpmas::api::model::AgentGroup::behavior ( )

pure virtual

Returns the Behavior associated to this group.

Returns: group's behavior

Implemented in fpmas::model::detail::AgentGroupBase.

◆ add()

virtual void fpmas::api::model::AgentGroup::add ( Agent * agent )

pure virtual

Adds a new Agent to this group.

AgentGroups to which an agent is added take ownership of the agent, that must be dynamically allocated (using a new statement). The agent lives while it belongs to at least one group, and is deleted when it is removed from the last group.

add() builds a new AgentNode into the current AgentGraph and associates it to the Agent if the agent was not contained in any group yet.

This group's groupId() is added to agents Agent::groupIds().

A task is also bound to the agent and Agent::groups() is updated as defined in insert().

Moreover, if the agent is LOCAL, the previous task is added to agentExecutionJob().

In consequence, it is possible to dynamically add() LOCAL agents to groups.

Notice that when the agent is not bound to a node yet, i.e. this is the first group the agent is inserted into so that a new node is built, the agent automatically becomes LOCAL, since the new node is built locally.

If a DISTANT agent is added to the group, it is just inserted in the group. However, this is a mechanic that must be used only internally, since adding a DISTANT agent to the group is not guaranteed to report the operation on other processes.

Parameters

agent agent to add

Implemented in fpmas::model::detail::AgentGroupBase.

◆ remove()

virtual void fpmas::api::model::AgentGroup::remove ( Agent * agent )

pure virtual

Removes an Agent from this group.

If this was the last group containing the Agent, it is completely removed from the simulation, so the associated AgentNode is also globally removed from the AgentGraph.

Else, the agent is simply removed from this group as defined in erase().

If the agent is LOCAL, the task associated to this group's behavior() is removed from agentExecutionJob().

Parameters

agent agent to remove

Implemented in fpmas::model::detail::AgentGroupBase.

◆ clear()

virtual void fpmas::api::model::AgentGroup::clear ( )

pure virtual

Removes all local agents from this group.

Implemented in fpmas::model::detail::AgentGroupBase.

◆ insert()

virtual void fpmas::api::model::AgentGroup::insert ( AgentPtr * agent )

pure virtual

Inserts an Agent into this AgentGroup.

This function is only used during the node migration process, and is not supposed to be used by the final user.

Contrary to add(), this method assumes that an AgentNode has already been built for the Agent.

When this method is called, it is assumed that agent's Agent::groupIds() list already contains this groupId(), so the agent should be inserted in the group.

Upon return, agent's Agent::groups() must be updated, and a task that execute behavior() on this agent must be bound to the agent. The corresponding task is then accessible from Agent::task(GroupId) and Agent::tasks().

Parameters

agent agent to insert into this group

Implemented in fpmas::model::detail::AgentGroupBase.

◆ erase()

virtual void fpmas::api::model::AgentGroup::erase ( AgentPtr * agent )

pure virtual

Erases an Agent from this AgentGroup.

This function is only used during the node migration process, and is not supposed to be used by the final user.

Contrary to remove(), this method does not globally removes the Agent (and its associated AgentNode) from the simulation.

Upon return, agent's Agent::groupIds() and Agent::groups() must be updated, and the task previously bound to the agent by insert() must be unbound.

Parameters

agent agent to erase from this group

Implemented in fpmas::model::detail::AgentGroupBase.

◆ agents()

virtual std::vector< Agent * > fpmas::api::model::AgentGroup::agents ( ) const

pure virtual

Returns the list of all Agents currently in this AgentGroup, including DISTANT representations of Agents not executed on the current process.

The returned list is invalidated by the following operations:

fpmas::api::graph::DistributedGraph::synchronize()
fpmas::api::synchro::Mutex::read() or fpmas::api::synchro::Mutex::acquire() on any Agent of the list.

Returns: Agents in this group

Implemented in fpmas::model::detail::AgentGroupBase.

◆ localAgents()

virtual std::vector< Agent * > fpmas::api::model::AgentGroup::localAgents ( ) const

pure virtual

Returns the list of LOCAL Agents currently in this AgentGroup, that are executed on the current process.

The returned list is invalidated by the following operations:

fpmas::api::graph::DistributedGraph::synchronize()
fpmas::api::synchro::Mutex::read() or fpmas::api::synchro::Mutex::acquire() on any Agent of the list.

Returns: LOCAL Agents in this group

Implemented in fpmas::model::detail::AgentGroupBase.

◆ distantAgents()

virtual std::vector< Agent * > fpmas::api::model::AgentGroup::distantAgents ( ) const

pure virtual

Returns the list of DISTANT Agents currently in this AgentGroup, represented to preserve LOCAL agents neighbors but not executed on this process.

The process on which a DISTANT agent is executed can be retrieved with agent->node()->location().

The returned list is invalidated by the following operations:

fpmas::api::graph::DistributedGraph::synchronize()
fpmas::api::synchro::Mutex::read() or fpmas::api::synchro::Mutex::acquire() on any Agent of the list.

Returns: DISTANT Agents in this group

Implemented in fpmas::model::detail::AgentGroupBase.

◆ job() [1/2]

virtual api::scheduler::Job & fpmas::api::model::AgentGroup::job ( )

pure virtual

Returns a reference to the Job associated to this AgentGroup.

This Job contains all the AgentTasks associated to all Agents in this group.

This Job can be scheduled to define when this AgentGroup must be executed.

Example: // Schedules agent_group to be executed from iteration 10 with a

// period of 2

scheduler.schedule(10, 2, agent_group.job());

See the complete api::scheduler::Scheduler interface for more scheduling options.

This method as been deprecated and will be removed in a next release. Use agentExecutionJob() or jobs() instead, depending on use case.

Implemented in fpmas::model::detail::AgentGroupBase.

◆ job() [2/2]

virtual const api::scheduler::Job & fpmas::api::model::AgentGroup::job ( ) const

pure virtual

Returns a reference to the Job associated to this AgentGroup.

This Job contains all the AgentTasks associated to all Agents in this group.

This Job can be scheduled to define when this AgentGroup must be executed.

Example: // Schedules agent_group to be executed from iteration 10 with a

// period of 2

scheduler.schedule(10, 2, agent_group.job());

See the complete api::scheduler::Scheduler interface for more scheduling options.

This method as been deprecated and will be removed in a next release. Use agentExecutionJob() or jobs() instead, depending on use case.

Implemented in fpmas::model::detail::AgentGroupBase.

◆ agentExecutionJob() [1/2]

virtual api::scheduler::Job & fpmas::api::model::AgentGroup::agentExecutionJob ( )

pure virtual

Returns a reference to the internal Job specifically used to execute behavior() on the agents() of the group.

Any necessary graph synchronization is included at the end of the Job, after all agents execution.

However this job is not intended to be scheduled directly: use jobs() instead.

Returns: agent execution job

See also: jobs()

Implemented in fpmas::model::detail::AgentGroupBase.

◆ agentExecutionJob() [2/2]

virtual const api::scheduler::Job & fpmas::api::model::AgentGroup::agentExecutionJob ( ) const

pure virtual

Returns a reference to the internal Job specifically used to execute behavior() on the agents() of the group.

Any necessary graph synchronization is included at the end of the Job, after all agents execution.

However this job is not intended to be scheduled directly: use jobs() instead.

Returns: agent execution job

See also: jobs()

Implemented in fpmas::model::detail::AgentGroupBase.

◆ jobs()

virtual api::scheduler::JobList fpmas::api::model::AgentGroup::jobs ( ) const

pure virtual

Returns the list of Jobs associated to this group.

This list must at least contain the agentExecutionJob(). Extra processes might be added internally to ensure the proper execution of Agents: in consequence, this list of job can be safely scheduled to plan agents execution.

Example: // Schedules agent_group to be executed from iteration 10 with a

// period of 2

scheduler.schedule(10, 2, agent_group.jobs());

See the complete api::scheduler::Scheduler interface for more scheduling options.

Returns: list of jobs associated to this group

Implemented in fpmas::model::detail::AgentGroup, and fpmas::model::MoveAgentGroup< CellType >.

◆ addEventHandler()

virtual void fpmas::api::model::AgentGroup::addEventHandler	(	Event	event,
		api::utils::Callback< Agent * > *	callback
	)

pure virtual

Registers a callback function to be called when the specified Event is emitted.

Parameters

event	event that triggers the callback
callback	callback called when the event occurs

Implemented in fpmas::model::detail::AgentGroupBase.

◆ removeEventHandler()

virtual void fpmas::api::model::AgentGroup::removeEventHandler	(	Event	event,
		api::utils::Callback< Agent * > *	callback
	)

pure virtual

Unregisters a callback function previously registered for the spespecified event.

The behavior is undefined if the callback was not previously registered using addEventHandler().

Parameters

event	event that triggers the callback
callback	callback called when the event occurs

Implemented in fpmas::model::detail::AgentGroupBase.

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

src/fpmas/api/model/model.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Event

Member Function Documentation

◆ groupId()

◆ behavior()

◆ add()

◆ remove()

◆ clear()

◆ insert()

◆ erase()

◆ agents()

◆ localAgents()

◆ distantAgents()

◆ job() [1/2]

◆ job() [2/2]

◆ agentExecutionJob() [1/2]

◆ agentExecutionJob() [2/2]

◆ jobs()

◆ addEventHandler()

◆ removeEventHandler()