Distributed computation is implemented on two levels:
- component level, where components of the same type located in different nodes communicate with each other to provide their services to all nodes,
- root agent level, where a transparent translation between a local agent environment and distributed environment is performed for: queries, actions, messages, agent migration.
Distributed Components
The following components work currently in the distributed mode (i.e., they automatically perform some actions in distributed environment in order for nodes to cooperate):
- DefaultLifecycleManager
- DefaultWorkplaceManager
- DefaultConfigurationService
They all are constructed quite similarly to each other. Each of them has its own kind of message (a class for messages and a separate class for headers) and sends them through a dedicated communication channel obtained from the communication manager.
There is no default addressing mechanism for distributed components. This is a responsibility of the component to check whether message is directed to its owning node.
There is also no default mechanism for inter-node communication for components of different types. It can be however easily done by obtaining the communication channel with a target component type name.
Distributed Agent Operations
Several operations that may be requested by agents need to be handled in a special way by the platform when performed in the distributed environment.
All of the agent operations that are described here take place only for simple (steppable) agents and SimpleWorkplace as only these are provided by the platform.
Agent Migrations
Distributed agent migrations occur on the agents from the second level of the agent tree.
Limitations include:
- only leaf agents can be migrated (so no aggregate migrations),
- migrating agents must be serializable,
- failed migration may cause a loss of the migrated agent.
Agent Messages
Messages sent to agents located in another node are simply wrapped in the WorkplaceManagerMessage instance and sent using the WorkplaceManager's communication channel. There are no limitations (messages must be serializable but it is a general requirement).
Actions
Only aggregate actions are discussed here and implemented by default. All other actions need to be handled by the user.
| Action | Implemented for DE? | Limitations and comments |
|---|---|---|
| sendMessage |  | none |
| passToParent |  | not possible, as top-level agents have no parent (there is, however, lack of consequence in the platform, because theoretically we have the "virtual root agent") |
| moveAgent | | the same as for agent migration |
| removeAgent | | require the workplace removal logic in the WorkplaceManager; and honestly its meaning for top-level agents is dubious, it may, however, be useful for the workplace migration in the future |
| killAgent | | require the workplace removal logic in the WorkplaceManager; this is actually more practical than simple removal because it destroys the workplace |
| addAgent | | require the workplace creation logic in the WorkplaceManager; and honestly its meaning for top-level agents is dubious, it may, however, be useful for the workplace migration in the future |
| getAgent | | should not occur in the top-level agents |
All translation logic is implemented in SimpleWorkplace. You can find more details in submitAction and all handleAction methods. Some of the actions require cooperation from the WorkplaceManger and they are triggered by method calls to the WorkplaceEnvironment interface.
Queries
Distributed queries are the most complicated element of the distributed environment and they differ greatly from the common queries. The reasons behind this are:
- we cannot sensibly serialize the full agent tree,
- the current implementation of queries is also not serializable,
- we do not want to introduce workplace proxies.
The distributed queries has been implemented as continuously running local queries with a global cache. The user defines a set of queries in the computation configuration for each simple workplace. These queries are executed by the workplace on a top-level agent that it executes. The results are saved into a distributed, global map using the WorkplaceEnvironment interface. These results are grouped by the query class. When the user performs a query on the top-level agents, these cached results are returned.
Implementation Tips
I need to know addresses of all workplaces (top-level agents) in the distributed environment. How can I do this?
When using DefaultWorkplaceManager, you should obtain a distributed map with the name provided by the org.jage.workplace.manager.DefaultWorkplaceManager#WORKPLACES_MAP_NAME constant from the communication manager. The map has following type: IMap<NodeAddress, Set<AgentAddress>>. You should treat this map as read-only.