Agent
Container for an agent-based modeling layer that runs alongside KSL's process view. Following the precedent of ksl.modeling.entity.TaskProcessingSystem, an AgentModel ships two kinds of agent — transient and permanent — plus the supporting machinery (a shared message bus, inner-class Statechart and AgentMailbox) that lets both kinds work uniformly.
Transient and permanent split:
Agent: a transient
Entity-based actor (aninner class). AQObjectunder the hood, not aModelElement, so it can be constructed during a replication. No automatic per-agent statistics. Use for arrival-driven populations, swarms, dynamic coalitions.PermanentAgent: a
ModelElement-derived setup-time actor. Constructed beforesimulate()runs. Full KSL lifecycle hooks and can register per-agentResponse/TWResponsestatistics. Use for structural cast members, named role-holders, anything where you want individual stats.
Both implement AgentLike (mailbox + name + currentTime) so the same Statechart and AgentMailbox machinery serves both.
Messaging:
A single
BlockingQueuemessage bus is pre-allocated atAgentModelconstruction. All sends route through it; mailboxes are POJOs that filter by recipient reference. This is what makes transient agents possible — agent construction no longer creates aModelElementchild.Per-mailbox queue statistics are not collected automatically. Permanent agents can register their own
Response/TWResponseobservers if they want individual stats (see the ksl.modeling.entity.TaskProcessingSystem.TaskProcessorPerformance pattern).
Statechart:
Statechart is an
inner classofAgentModel, not aModelElement. It uses the outer'sprotected schedule(...)andexecutiveto schedule timeout events and register conditional actions. Lifecycle (start/stop on replication boundaries) is driven byAgentModel.initialize()/afterReplication()for transientAgents, and by eachPermanentAgent/AgentResource's own lifecycle hooks for the permanent case.
Parameters
the parent model element
an optional name for the agent model
Types
An autonomous, reactive actor. An Agent is a ProcessModel.Entity (and therefore a QObject, not a ModelElement), so instances can be constructed at any time — including during a running replication. Each agent gets a POJO mailbox for receiving messages and may optionally have a statechart.
Schedules the creation of agents over time and activates each agent's default process. Mirror of ksl.modeling.entity.ProcessModel.EntityGenerator but produces Agent instances. The agent must have defaultProcess configured.
A typed mailbox that holds AgentMessage values for a single AgentLike owner.
Per-agent statistics observer for a PermanentAgent. Modeled on ksl.modeling.entity.TaskProcessingSystem.TaskProcessorPerformance: a ModelElement that subscribes to a specific mailbox via MailboxObserver (and optionally a statechart via StatechartObserver) and publishes standard KSL Response/TWResponse instances.
Observer hook notified when an agent — Agent (setup-time or transient/runtime), PermanentAgent, or AgentResource — is constructed and registered with this model. Its purpose is to hand external/integration/reporting code a reference to every agent that comes into existence, including transient agents created during a replication that are not in the agents registry and could not otherwise be referenced.
A typed collection of agents with optional Projections attached. Modeled on Repast Simphony's context concept: membership lives here, structure (positions, edges, networks) lives in attached projections.
Observer hook for an AgentMailbox. Called for every successful delivery (whether the message was queued or handed off directly to a waiting receiver) and for every successful consumption (whether via tryTake, consume, or Waiter match). Used by AgentPerformance to gather mailbox traffic statistics without coupling the mailbox to the statistics machinery.
A setup-time agent that is a ModelElement. Use when you need KSL lifecycle hooks (initialize, warmUp, afterReplication) on the agent itself, or want to own per-agent Response/TWResponse statistics. Modeled on ksl.modeling.entity.TaskProcessingSystem.TaskProcessor: a ModelElement wrapper that holds its own POJO mailbox and statechart and drives their lifecycle through its own hooks.
A flat statechart attached to an AgentLike owner. Behavior consists of a finite set of named states; the chart is always in exactly one state once started.
Observer hook for a Statechart. Fires on every state entry, state exit, and completed transition. Used by AgentPerformance to gather statechart-state statistics (time-in-state, entry counts, transition counts).
Properties
Number of currently-attached AgentRegistryObservers (for diagnostics).
Functions
It is essential that subclasses that override this function call the super. This ensures that suspended entities are cleaned up after a replication
Register an AgentRegistryObserver to be notified when any agent (setup-time or transient) is constructed and registered with this model. Typically attached at setup time. See AgentRegistryObserver.
Remove a previously-attached AgentRegistryObserver. No-op if not attached.
When an entity is disposed (e.g., a transient Agent whose process completed and is being reclaimed), stop its statechart so its subscriptions are torn down promptly rather than waiting for the end-of-replication sweep.
This method should be overridden by subclasses that need actions performed to initialize prior to a replication. It is called once before each replication occurs if the model element wants initialization. It is called after beforeReplication() is called