Unverified Commit c9048dcc authored by oanaBiancaSchiopu's avatar oanaBiancaSchiopu Committed by GitHub
Browse files

add-documentation-for-signals-with-variables (#785)



* add-documentation-for-signals-with-variables

* refactor-after-code-reviews

* refactor-after-reviews

* refactor-after-reviews
Co-authored-by: default avatarOana Schiopu <oana-schiopu@activeeon.com>
parent ccc68b80
...@@ -2618,26 +2618,33 @@ A complete example of Producer / Consumer, _ServiceDeployerConsumer_ can be down ...@@ -2618,26 +2618,33 @@ A complete example of Producer / Consumer, _ServiceDeployerConsumer_ can be down
=== Signal API === Signal API
The *Signal API* is a high-level API that enables users to interact with running jobs via signals (we also call them actions). The *Signal API* is a high-level API that enables users to interact with running jobs via signals (we also call them actions).
That is, it allows a job to expose specific signals (e.g., `soft_stop` to properly finish a job) that can be triggered by users from the *Workflow Execution portal*. That is, it allows a job to expose specific signals (e.g., `soft_stop` to properly finish a job) that can be triggered by users from the *Workflow Execution portal* or *Scheduler portal*.
You can try the <<_examples_2,examples>> below to better understand how it works. You can try the <<_examples_2,examples>> below to better understand how it works.
In summary and for simple use, just go to <<_proactive_studio, ProActive Studio>> and use the 2 predefined templates in the Controls menu: *Check_For_Signals* or *Wait_For_Signals*. In summary and for simple use, just go to <<_proactive_studio, ProActive Studio>> and use the 2 predefined templates in the Controls menu: *Check_For_Signals* or *Wait_For_Signals*.
Fill up the Task Variable *SIGNALS*, and use those templates in your own workflow to be able to receive input from, for instance, the Workflow Execution portal. Fill up the Task Variable *SIGNALS*, and use those templates in your own workflow to be able to receive input from, for instance, the Workflow Execution portal or Scheduler portal.
At a more detailed level and advanced use, the Signal API allows jobs and users to exchange signals using a communication channel provided by the <<_task_synchronization_api,synchronization API>>. At a more detailed level and advanced use, the Signal API allows jobs and users to exchange signals using a communication channel provided by the <<_task_synchronization_api,synchronization API>>.
The typical usage scenario of the Signal API is the following: The typical usage scenario of the Signal API is the following:
. A job declares to be ready to handle one or more signals. The signals are then displayed in the Workflow Execution portal (e.g., display the `soft_stop` signal). . Signals are defined by their name and, optionally, a list of variables. Variables attached to a signal have the same structure as <<_workflow_variables>> but are declared exclusively using the <<_task_signal_api,Signal API>>.
. If the signal has variables, then a new window will appear where the user can set the variables values and then send the signal with variables to the job. If the signal does not have variables then the window will not appear.
Adding variables to a signal allows to enhance the manual control of the workflow execution.
After receiving the signal with attached variables, the workflow will then need to process this information and react accordingly (e.g. continue a calculation with a new set of parameters, etc...)
. A job declares to be ready to handle one or more signals that can have attached variables. The signals are then displayed in the Workflow Execution portal or Scheduler portal(e.g., display the `soft_stop` signal).
. The job waits to receive these signals, or check for their reception regularly. . The job waits to receive these signals, or check for their reception regularly.
. A user clicks on the signal displayed in the Workflow Execution portal (e.g., click on the `soft_stop` signal), which sends this signal to the job. . A user clicks on the signal displayed in the Workflow Execution portal or Scheduler portal (e.g., click on the `soft_stop` signal), which sends this signal to the job.
. At the signal reception, the job executes the corresponding behavior (defined in the workflow). . At the signal reception, the job executes the corresponding behavior (defined in the workflow).
When the signal has attached variables, variables must be valid according to their model specification (see <<_variable_model,Variable Model>>). Sending a signal will not be possible unless they are validated.
As already mentioned, the Signal API uses the <<_task_synchronization_api,synchronization API>> to store jobs' signals, with respect to the following specifications: As already mentioned, the Signal API uses the <<_task_synchronization_api,synchronization API>> to store jobs' signals, with respect to the following specifications:
* It uses a single persistent channel (called *PA_SIGNALS_CHANNEL*) to store the signals of all jobs. The signal channel contains an entry per job. * It uses a single persistent channel (called *PA_SIGNALS_CHANNEL + {jobId}*) to store the signals and variables of all jobs. The signal channel contains an entry per signal.
* Job signals are automatically removed when the job execution finishes (i.e., the job is in the status Finished, Cancelled, Failed or Killed). * Job signals are automatically removed when the job execution finishes (i.e., the job is in the status Finished, Cancelled, Failed or Killed).
...@@ -2652,23 +2659,27 @@ The Signal API is available inside ProActive Tasks through the *signalapi* <<_gl ...@@ -2652,23 +2659,27 @@ The Signal API is available inside ProActive Tasks through the *signalapi* <<_gl
It is easy to use, and offers a set of basic operations on signals summarized as follows: It is easy to use, and offers a set of basic operations on signals summarized as follows:
* *readyForSignal*: declares that the current job is ready to receive and handle one or more signals. * *readyForSignal*: declares that the current job is ready to receive and handle one or more signals with or without variables.
Variables are passed as a list of link:../javadoc/org/ow2/proactive/scheduler/common/job/JobVariable.html[JobVariable objects]
This operation constructs new signals (by adding the prefix `ready_` to the input signals), then adds them to job signals. This operation constructs new signals (by adding the prefix `ready_` to the input signals), then adds them to job signals.
For example, if a job declares ready for the signal `soft_stop`, the signal `ready_soft_stop` is added to the set of job signals. For example, if a job declares ready for the signal `soft_stop`, the signal `ready_soft_stop` is added to the set of job signals.
Additionally, if the input signal (e.g., `soft_stop`) already exists among the job signals (which means that it has been sent and handled previously), Additionally, if the input signal (e.g., `soft_stop`) already exists among the job signals (which means that it has been sent and handled previously),
the operation ready for signal automatically removes it, thus the job is ready again to receive and handle the same signal. the operation ready for signal automatically removes it, thus the job is ready again to receive and handle the same signal.
* *sendSignal*, *sendManySignals*: adds one or more signals given as input to the current job signals. * *sendSignal*, *sendManySignals*: sends programmatically one or more signals with or without variables given as input to the current job signals.
This operation removes the corresponding ready signals if they already exist. For instance, sending `soft_stop` removes the signal This operation removes the corresponding ready signals if they already exist. For instance, sending `soft_stop` removes the signal
`ready_soft_stop` if it already exists among the job signals. `ready_soft_stop` if it already exists among the job signals.
Though signals are meant to be sent manually by a human user through to ProActive web portals, it is also possible to use these methods to send them programmatically inside the workflow.
* *checkForSignals*: verifies whether one or more signals exist among the set of job signals. * *checkForSignals*: verifies whether all of the signals given as input exist among the set of job signals.
* *waitFor*, *waitForAny*: blocking instruction that waits until one signal (among those given as input) is added to the set of job signals. * *waitFor*, *waitForAny*: blocking instruction that waits until one signal (among those given as input) is added to the set of job signals.
The instruction _waitFor_ will return a map that represents the name and value of the signal variables.
_waitForAny_ instruction returns the first signal object that is received among those given as input
* *removeSignal*, *removeManySignals*: removes one or more signals from the set of job signals. * *removeSignal*, *removeManySignals*: removes one or more signals from the set of job signals.
* *getJobSignals*: returns the current job signals. * *getJobSignals*: returns the current job signals and variables.
In addition to the above operations available within ProActive Tasks, users and third-party systems can send signals In addition to the above operations available within ProActive Tasks, users and third-party systems can send signals
to a specific job via link:/doc/rest/#1218178377[ProActive Signals REST endpoint]. to a specific job via link:/doc/rest/#1218178377[ProActive Signals REST endpoint].
...@@ -2693,13 +2704,39 @@ signalapi.readyForSignal("soft_stop") ...@@ -2693,13 +2704,39 @@ signalapi.readyForSignal("soft_stop")
//Display current job signals //Display current job signals
println("Job signals "+ signalapi.getJobSignals()) println("Job signals "+ signalapi.getJobSignals())
//Wait util the 'soft_stop' signal is sent (via the Workflow Execution portal or REST API) //Wait util the 'soft_stop' signal is sent (via the Workflow Execution portal, Scheduler portal or REST API)
signalapi.waitFor("soft_stop") signalapi.waitFor("soft_stop")
//Remove the 'soft_stop' signal from the set of job signals //Remove the 'soft_stop' signal from the set of job signals
signalapi.removeSignal("soft_stop") signalapi.removeSignal("soft_stop")
---- ----
Here is another example of a groovy code that uses some Signal API operations with signal variables.
----
import org.ow2.proactive.scheduler.common.job.JobVariable
//Declare the signal variables
List <JobVariable> signalVariables = new java.util.ArrayList<JobVariable>()
signalVariables.add(variables.get("INTEGER_VARIABLE"))
signalVariables.add(variables.get("BOOLEAN_VARIABLE"))
//Declare that the current job is ready to receive and handle the 'soft_stop' signal with the given variables
signalapi.readyForSignal("soft_stop", signalVariables)
//Display current job signals
println("Job signals "+ signalapi.getJobSignals())
//Wait util the 'soft_stop' signal with variables is sent (via the Workflow Execution portal, Scheduler portal or REST API)
outputParameters = signalapi.waitFor("soft_stop")
//The outputParameters represent a hashmap containing the names of the variables and their values entered by the user
println "Output parameters = " + outputParameters
//Remove the 'soft_stop' signal from the set of job signals
signalapi.removeSignal("soft_stop")
----
===== Usage of the Signals REST endpoint ===== Usage of the Signals REST endpoint
Below, we provide an example based on link:https://curl.se/[curl], which shows how to use the link:/doc/rest/#1218178377[Signals REST endpoint] for sending a signal to a specific job: Below, we provide an example based on link:https://curl.se/[curl], which shows how to use the link:/doc/rest/#1218178377[Signals REST endpoint] for sending a signal to a specific job:
[source,shell,subs="verbatim,quotes"] [source,shell,subs="verbatim,quotes"]
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment