From 76ff282fb8100dfd1596663ebaf6283316e0cb66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Galland?= Date: Fri, 16 Dec 2016 13:33:36 +0100 Subject: [PATCH] [docs] New spawning API. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit see #481 see #76 Signed-off-by: Stéphane Galland --- .../docs/gettingstarted/RunSARLAgentJava.spec | 6 +- .../test/java/io/sarl/docs/reference/BIC.spec | 112 ++++++++++-------- .../docs/tutorials/CreateSREWithTinyMAS.spec | 96 ++++++++------- .../java/io/sarl/docs/tutorials/PingPong.spec | 7 +- .../io/sarl/docs/tutorials/PingPongSpace.spec | 7 +- 5 files changed, 127 insertions(+), 101 deletions(-) diff --git a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/gettingstarted/RunSARLAgentJava.spec b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/gettingstarted/RunSARLAgentJava.spec index 037f8c04ee..a9fa918720 100644 --- a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/gettingstarted/RunSARLAgentJava.spec +++ b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/gettingstarted/RunSARLAgentJava.spec @@ -83,7 +83,7 @@ describe "Run SARL Agent from a Java Program" { * you could use the `Kernel` instance provided by Janus. * This instance is replied by the `startJanus` function of the `Boot` class. * - *

The `Kernel` type provides the `spawn` function, which permits launching + *

The `Kernel` type provides the `spawn` functions, which permit launching * an agent programmatically. * *

The previous example could be updated for launching two agents of the same type. @@ -95,8 +95,8 @@ describe "Run SARL Agent from a Java Program" { *

The second parameter of the `spawn` function is the list of parameters to * pass with the `Initialize` event to the launched agent. * - *

Note that the first agent is launched by the `startJanus` function, and the - * second agent is launched by the `spawn` function. + * that the first agent is launched by the `startJanus` function, and the + * second agent is launched by the `spawn` function. * * @filter(.* = '''|'''|.parse.*) */ diff --git a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/reference/BIC.spec b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/reference/BIC.spec index b802a219ed..0689c2d915 100644 --- a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/reference/BIC.spec +++ b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/reference/BIC.spec @@ -659,44 +659,6 @@ describe "Built-in Capacity Reference" { }".parseSuccessfully } - /* Many time, it is useful for agent to create a new agent - * into the default context. The following function is provided for this - * task: - * - * def spawn(agentType : Class, params : Object[]) : UUID - * - * - *

This action creates an instance of the given agent type, and launches the agent - * into the default context. The parameters are passed to the spawned agent inside - * the `Initialize` event: the `parameters` field. - * - *

This action fires two events: - * - * * `AgentSpawned` in the default space of the default context. The source of the event is this spawner. - * * `Initialize` in spawned agent. - * - * @filter(.*) - */ - fact "Spawning an Agent"{ - " package io.sarl.docs.reference.bic - import io.sarl.core.DefaultContextInteractions - import io.sarl.lang.core.Agent - import java.util.UUID - agent A { - uses DefaultContextInteractions - def myaction { - var aid : UUID - var type : Class - var p1 : Object - var p2 : Object - type = typeof(A) - p1 = new Object - p2 = new Object - aid = spawn(type, #[p1, p2]) - } - }".parseSuccessfully - } - /* The core mechanism for information exchanges among agents is * [event-based](EventReferenceSpec.html). * For sending an event in the default space of the default context, @@ -921,17 +883,70 @@ describe "Built-in Capacity Reference" { }".parseSuccessfully } - /* Many time, it is useful for an agent to create a new agent - * into a given context. The following function is provided for this + /* Many time, it is useful for agent to create a new agent + * into the default context. The following functions are provided for this * task: * + * def spawn(agentType : Class, parameters : Object*) : UUID + * + * def spawn(nbAgents: int, agentType : Class, parameters : Object*) : Collection + * + *

This action creates one to {@code nbAgents} instance(s) of the given agent type, and launches the agent(s) + * into the default context. + * The first `spawn` function above is spawning a single agent and replies the identifier of the spawned agent. + * The second `spawn` function is spawning the given number of agents and replies the identifiers of the + * spawned agents. + * The {@code parameters} are passed to the spawned agent inside + * the `Initialize` event: the `parameters` field. + * + *

This action fires two events: + * + * * `AgentSpawned` in the default space of the default context. The source of the event is this spawner. + * * `Initialize` in spawned agent. + * + * @filter(.*) + */ + fact "Spawning in the default context" { + " package io.sarl.docs.reference.bic + import io.sarl.core.Lifecycle + import io.sarl.lang.core.Agent + import java.util.UUID + import java.util.Collection + agent A { + uses Lifecycle + def myaction { + var aid : UUID + var listaid : Collection + var type : Class + var p1 : Object + var p2 : Object + type = typeof(A) + p1 = new Object + p2 = new Object + aid = spawn(type, p1, p2) + listaid = spawn(5, type, p1, p2) + } + }".parseSuccessfully + } + + /* When one or more agents should be spawned into a specific agent context, the two following functions + * could be used for launching the agents: + * * def spawnInContext(agentType : Class, * context : AgentContext, - * params : Object[]) : UUID + * parameters : Object*) : UUID * + * def spawnInContext(nbAgents : int, + * agentType : Class, + * context : AgentContext, + * parameters : Object*) : UUID * - *

This action creates an instance of the given agent type, and launches the agent - * into the given context. The parameters are passed to the spawned agent inside + *

This action creates one to {@code nbAgents} instance(s) of the given agent type, and launches the agent(s) + * into the given {@code context}. + * The first `spawn` function is spawning a single agent and replies the identifier of the spawned agent. + * The second `spawn` function is spawning the given number of agents and replies the identifiers of the + * spawned agents. + * The {@code parameters} are passed to the spawned agent inside * the `Initialize` event: the `parameters` field. * *

This action fires two events: @@ -941,24 +956,27 @@ describe "Built-in Capacity Reference" { * * @filter(.*) */ - fact "Spawning an Agent"{ + fact "Spawning in a specific context"{ " package io.sarl.docs.reference.bic import io.sarl.core.Lifecycle import io.sarl.lang.core.AgentContext import io.sarl.lang.core.Agent import java.util.UUID + import java.util.Collection agent A { uses Lifecycle def myaction { var c : AgentContext var aid : UUID + var listaid : Collection var type : Class var p1 : Object var p2 : Object type = typeof(A) p1 = new Object p2 = new Object - aid = spawnInContext(type, c, #[p1, p2]) + aid = spawnInContext(type, c, p1, p2) + listaid = spawnInContext(5, type, c, p1, p2) } }".parseSuccessfully } @@ -970,7 +988,7 @@ describe "Built-in Capacity Reference" { * def spawnInContextWithID(agentType : Class, * agentId : UUID, * context : AgentContext, - * params : Object[]) : UUID + * parameters : Object[]) : UUID * * *

This action creates an instance of the given agent type, with @@ -986,7 +1004,7 @@ describe "Built-in Capacity Reference" { * * @filter(.*) */ - fact "Spawning an Agent with a specific identifier"{ + fact "Spawning with a specific agent identifier"{ " package io.sarl.docs.reference.bic import io.sarl.core.Lifecycle import io.sarl.lang.core.AgentContext diff --git a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/CreateSREWithTinyMAS.spec b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/CreateSREWithTinyMAS.spec index 43aca3d467..0f2bcc0ba7 100644 --- a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/CreateSREWithTinyMAS.spec +++ b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/CreateSREWithTinyMAS.spec @@ -1239,17 +1239,16 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ describe "Definition of the Lifecycle skill" { /* Consider the agent execution mechanism in the tinyMAS platform: - * inside an infinite loop, each agent is run. This algorithmical + * inside an infinite loop, each agent is run. This algorithmic * principle may be described by the following algorithm: * - * ``` - * while (true) { - * for(a : whitePages.allAgents) { - * a.live - * } - * refreshKernelState - * } - * ``` + * while (true) { + * for(a : whitePages.allAgents) { + * a.live + * } + * refreshKernelState + * } + * * The tinyMAS platform is designed for updating the kernel state * after all the agent have been ran. * Consequently, the tinyMAS platform does not support the creation @@ -1258,10 +1257,10 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ * spawned agent must be delayed until the `refreshKernelState` is invoked. * *

This particular design of the tinyMAS platform is at the opposite of - * the standard spawning principle in SARL: in SARL the agents are spawn + * the standard spawning principle in SARL: the agents are spawned * when the spawning function is called. * - *

For solving this issue, we need to implement a buffer of spawned + *

For fixing this issue, we need to implement a buffer of spawned * agents, that will be filled by the SARL spawning functions, and consumed * by the `refreshKernelState` function. * @@ -1306,6 +1305,7 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ '''.parseSuccessfully( ''' package io.sarl.docs.tutorials.tinyMASSRE + import java.util.Collection import java.util.UUID import java.util.List import java.util.ArrayList @@ -1348,6 +1348,28 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ ''' class LifecycleSkill extends Skill implements Lifecycle { + def spawn( + agentClass : Class, + params : Object*) + : UUID { + return defaultSpace.spawn(agentClass, null, params) + } + + def spawn( + nbAgents : int, + agentClass : Class, + params : Object*) + : Collection { + var list = newArrayList + for (i : 1..nbAgents) { + var id = defaultSpace.spawn(agentClass, null, params) + if (id !== null) { + list += id + } + } + return list + } + def spawnInContext( agentClass : Class, context : AgentContext, @@ -1359,6 +1381,24 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ return null } + def spawnInContext( + nbAgents : int, + agentClass : Class, + context : AgentContext, + params : Object*) + : Collection { + var list = newArrayList + if (context.ID == defaultSpace.agentContext.ID) { + for (i : 1..nbAgents) { + var id = defaultSpace.spawn(agentClass, null, params) + if (id !== null) { + list += id + } + } + } + return list + } + def spawnInContextWithID( agentClass : Class, agentID : UUID, @@ -1380,6 +1420,7 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ '''.parseSuccessfully( ''' package io.sarl.docs.tutorials.tinyMASSRE + import java.util.Collection import java.util.UUID import io.sarl.core.Lifecycle import io.sarl.lang.core.AgentContext @@ -1481,8 +1522,7 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ } /* The `DefaultContextInteractions` capacity enables the agent to have - * interaction in the default space, and to spawn agents in the default - * context. + * interaction in the default space. */ describe "Definition of the DefaultContextInteractions skill" { @@ -1636,36 +1676,6 @@ describe "Creating a SARL Run-time Environment for the tinyMAS platform"{ typeof(DefaultContextInteractions) should haveDeprecatedMethod "receive(java.util.UUID,io.sarl.lang.core.Event)" } - /* Spawning an agent in the default context could be done by calling the `spawn` function of - * the `DefaultContextInteractions` capacity. - * This function delegates its behavior to the `spawn` function that is already defined - * in the tinyMAS-SARL default space class. - * - * @filter(.* = '''|'''|.parseSuccessfully.*) - */ - fact "Spawning agents in the default context" { - ''' - def spawn(agentType : Class, params : Object*) : UUID { - (defaultSpace as TMDefaultSpace).spawn(agentType, null, params) - } - '''.parseSuccessfully( - ''' - package io.sarl.docs.tutorials.tinyMASSRE - import java.util.UUID - import io.sarl.lang.core.EventSpace - import io.sarl.core.DefaultContextInteractions - interface TMDefaultSpace extends EventSpace { - def spawn(agentType : Class, agentID : UUID, params : Object*) : UUID - } - abstract class DefaultContextInteractionsSkill implements DefaultContextInteractions { - def getDefaultSpace : EventSpace { null } - ''', - // TEXT - ''' - } - ''') - } - } /* The `Behaviors` capacity enables the agent to have diff --git a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPong.spec b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPong.spec index d1401aa8b4..9f416cb406 100644 --- a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPong.spec +++ b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPong.spec @@ -636,20 +636,20 @@ describe "Agent Communication with the Ping Pong Agents"{ */ describe "Method 2: Execute all the agents in a single instance of Janus" { - /* The boot agent uses the `DefaultContextInteractions` + /* The boot agent uses the `Lifecycle` * capacity for launching agents in the default context. * This capacity provides the function `spawn(Class)` * for launching an agent of the given type. * When the boot agent has launched the two expected agents, * it is killing itself. This is done with the `killMe` - * function, which is provided by the `Lifecycle` capacity. + * function, which is provided by the `Lifecycle` capacity too. * * @filter(.* = '''|'''|.parseSuccessfully.*) */ fact "Defining the Boot agent" { ''' agent BootAgent { - uses DefaultContextInteractions, Lifecycle + uses Lifecycle on Initialize { spawn( PongAgent ) spawn( PingAgent ) @@ -658,7 +658,6 @@ describe "Agent Communication with the Ping Pong Agents"{ } '''.parseSuccessfully( "package io.sarl.docs.tutorials.pingpong - import io.sarl.core.DefaultContextInteractions import io.sarl.core.Initialize import io.sarl.core.Lifecycle agent PongAgent { } diff --git a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec index 2518282843..edc705cc11 100644 --- a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec +++ b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec @@ -832,20 +832,20 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ */ describe "Method 2: Execute all the agents in a single instance of Janus" { - /* The boot agent uses the `DefaultContextInteractions` + /* The boot agent uses the `Lifecycle` * capacity for launching agents in the default context. * This capacity provides the function `spawn(Class)` * for launching an agent of the given type. * When the boot agent has launched the two expected agents, * it is killing itself. This is done with the `killMe` - * function, which is provided by the `Lifecycle` capacity. + * function, which is provided by the `Lifecycle` capacity too. * * @filter(.* = '''|'''|.parseSuccessfully.*) */ fact "Defining the Boot agent" { ''' agent BootAgent { - uses DefaultContextInteractions, Lifecycle + uses Lifecycle on Initialize { spawn( PongAgent ) spawn( PingAgent ) @@ -854,7 +854,6 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ } '''.parseSuccessfully( "package io.sarl.docs.tutorials.pingpongspace - import io.sarl.core.DefaultContextInteractions import io.sarl.core.Initialize import io.sarl.core.Lifecycle agent PongAgent { }