Skip to content

Commit

Permalink
[lang][core] Add @SarlAsynchronousExecution for helping the editor to…
Browse files Browse the repository at this point in the history 
… show asynchronous API functions.

Signed-off-by: Stéphane Galland <galland@arakhne.org>
  • Loading branch information
@gallandarakhneorg
gallandarakhneorg committed Mar 13, 2021
1 parent 548ca2d commit 9bbb0ad
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 0 deletions.
41 changes: 41 additions & 0 deletions main/apiplugins/io.sarl.core/src/main/sarl/io/sarl/core/bic.sarl
View file
Expand Up @@ -37,6 +37,7 @@ import java.util.UUID
import java.util.concurrent.TimeUnit
import java.util.function.Supplier
import java.util.logging.Logger
import io.sarl.lang.annotation.SarlAsynchronousExecution

/**
* Provides functions for accessing and managing the external contexts of an agent.
Expand Down Expand Up @@ -175,6 +176,8 @@ capacity ExternalContextAccess {
* @param scope the definition of the scope that will be used for selected the receivers of the events. If {@code null}, all the agents in the space will receive the event.
* @since 0.6
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def emit(^space : EventSpace, ^event : Event, scope : Scope<Address> = null)

}
Expand Down Expand Up @@ -350,6 +353,8 @@ capacity Behaviors {
* @param event the event to emit to the agent's behaviors and in the internal context.
* @param scope the definition of the scope that will be used for selected the receivers of the events.
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def wake(^event : Event, scope : Scope<Address> = null)

/**
Expand All @@ -364,6 +369,8 @@ capacity Behaviors {
* @param event the event to emit to the agent's behaviors and in the internal context.
* @since 0.12
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def wake(^behavior : Behavior, ^event : Event)

/**
Expand All @@ -378,6 +385,8 @@ capacity Behaviors {
* @param event the event to emit to the agent's behaviors and in the internal context.
* @since 0.12
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def wake(behaviors : Iterable<Behavior>, ^event : Event)

/**
Expand All @@ -403,6 +412,8 @@ capacity Lifecycle {
* <p>Caution: when this function returns, there is no warranty that the spawned agent
* is initialized at the time of the return.
* Indeed, agent spawning is done in parallel to the calling thread.
* This parallel task for spawning is not considered as an agent task, i.e. it cannot
* be stopped or cancelled by the spawning agent, or if this agent is killed.
*
* <p>This function does nothing if one of the following conditions evaluates to true:
* <ul>
Expand All @@ -415,6 +426,8 @@ capacity Lifecycle {
* @fires AgentSpawnFailure if the agent cannot be spawned.
* @since 0.5
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def spawn(agentType : Class<? extends Agent>, params : Object*) fires AgentSpawned, AgentSpawnFailure

/**
Expand All @@ -425,6 +438,8 @@ capacity Lifecycle {
* <p>Caution: when this function returns, there is no warranty that the spawned agents
* are initialized at the time of the return.
* Indeed, agent spawning is done in parallel to the calling thread.
* This parallel task for spawning is not considered as an agent task, i.e. it cannot
* be stopped or cancelled by the spawning agent, or if this agent is killed.
*
* <p>This function does nothing if one of the following conditions evaluates to true:
* <ul>
Expand All @@ -439,6 +454,8 @@ capacity Lifecycle {
* @fires AgentSpawnFailure if the agent cannot be spawned.
* @since 0.5
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def spawn(nbAgents : int, agentType : Class<? extends Agent>, params : Object*) fires AgentSpawned, AgentSpawnFailure

/**
Expand All @@ -447,6 +464,8 @@ capacity Lifecycle {
* <p>Caution: when this function returns, there is no warranty that the spawned agent
* is initialized at the time of the return.
* Indeed, agent spawning is done in parallel to the calling thread.
* This parallel task for spawning is not considered as an agent task, i.e. it cannot
* be stopped or cancelled by the spawning agent, or if this agent is killed.
*
* <p>This function does nothing if one of the following conditions evaluates to true:
* <ul>
Expand All @@ -459,6 +478,8 @@ capacity Lifecycle {
* @fires AgentSpawned inside the default context of the parent. The source of the event is this agent.
* @fires AgentSpawnFailure if the agent cannot be spawned.
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def spawnInContext(agentClass : Class <? extends Agent>, context : AgentContext, params : Object*) fires AgentSpawned, AgentSpawnFailure

/**
Expand All @@ -467,6 +488,8 @@ capacity Lifecycle {
* <p>Caution: when this function returns, there is no warranty that the spawned agents
* are initialized at the time of the return.
* Indeed, agent spawning is done in parallel to the calling thread.
* This parallel task for spawning is not considered as an agent task, i.e. it cannot
* be stopped or cancelled by the spawning agent, or if this agent is killed.
*
* <p>This function does nothing if one of the following conditions evaluates to true:
* <ul>
Expand All @@ -482,6 +505,8 @@ capacity Lifecycle {
* @fires AgentSpawnFailure if the agent cannot be spawned.
* @since 0.5
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def spawnInContext(nbAgents : int, agentClass : Class <? extends Agent>, context : AgentContext, params : Object*) fires AgentSpawned, AgentSpawnFailure

/**
Expand All @@ -490,6 +515,8 @@ capacity Lifecycle {
* <p>Caution: when this function returns, there is no warranty that the spawned agent
* is initialized at the time of the return.
* Indeed, agent spawning is done in parallel to the calling thread.
* This parallel task for spawning is not considered as an agent task, i.e. it cannot
* be stopped or cancelled by the spawning agent, or if this agent is killed.
*
* <p>This function does nothing if one of the following conditions evaluates to true:
* <ul>
Expand All @@ -503,6 +530,8 @@ capacity Lifecycle {
* @fires AgentSpawned inside the default context of the parent. The source of the event is this agent.
* @fires AgentSpawnFailure if the agent cannot be spawned.
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def spawnInContextWithID(agentClass : Class <? extends Agent>, agentID : UUID, context : AgentContext, params : Object*) fires AgentSpawned, AgentSpawnFailure

/**
Expand All @@ -511,6 +540,8 @@ capacity Lifecycle {
* <p>Caution: when this function returns, there is no warranty that the spawned agent
* is initialized at the time of the return.
* Indeed, agent spawning is done in parallel to the calling thread.
* This parallel task for spawning is not considered as an agent task, i.e. it cannot
* be stopped or cancelled by the spawning agent, or if this agent is killed.
*
* <p>This function does nothing if one of the following conditions evaluates to true:
* <ul>
Expand All @@ -524,6 +555,8 @@ capacity Lifecycle {
* @fires AgentSpawnFailure if the agent cannot be spawned.
* @since 0.12
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def spawnWithID(agentClass : Class <? extends Agent>, agentID : UUID, params : Object*) fires AgentSpawned, AgentSpawnFailure

/**
Expand Down Expand Up @@ -830,6 +863,8 @@ capacity DefaultContextInteractions {
* @param event the event to emit.
* @param scope the definition of the scope that will be used for selected the receivers of the events. If {@code null}, all the agents in the space will receive the event.
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def emit(^event : Event, scope : Scope<Address> = null)

/**
Expand Down Expand Up @@ -857,6 +892,8 @@ capacity DefaultContextInteractions {
* @param scope the definition of the scope that will be used for selected the receivers of the events. If {@code null}, all the agents in the space will receive the event.
* @since 0.12
*/
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def emitToParent(^event : Event)

/**
Expand All @@ -868,6 +905,8 @@ capacity DefaultContextInteractions {
* @deprecated since 0.11, see {@link #emit(Event,Scope)}
*/
@Deprecated
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def willReceive(receiver : UUID, ^event : Event)

/** Replies if the given space is the default space of the default context.
Expand Down Expand Up @@ -946,6 +985,8 @@ capacity DefaultContextInteractions {
* @deprecated See the {@link Lifecycle} capacity.
*/
@Deprecated
@SuppressWarnings("use_reserved_sarl_annotation")
@SarlAsynchronousExecution
def spawn(agentType : Class<? extends Agent>, params : Object*) : UUID fires AgentSpawned, AgentSpawnFailure

}
Expand Down
45 changes: 45 additions & 0 deletions .../coreplugins/io.sarl.lang.core/src/io/sarl/lang/annotation/SarlAsynchronousExecution.java
View file
@@ -0,0 +1,45 @@
/*
* $Id$
*
* SARL is an general-purpose agent programming language.
* More details on http://www.sarl.io
*
* Copyright (C) 2014-2021 the original authors or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package io.sarl.lang.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/** Annotation for marking a function that is supposed to be run in parallel.
* Any function that is marked with this annotation may return from its call
* before the expected behavior of the function is really ran. In other words,
* It is an indicator that may be used by the SARL editor for displaying this function
* in a different way to the SARL developper.
*
* @author $Author: sgalland$
* @version $FullVersion$
* @mavengroupid $GroupId$
* @mavenartifactid $ArtifactId$
* @since 0.12
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SarlAsynchronousExecution {
//
}

0 comments on commit 9bbb0ad

Please sign in to comment.