3.8 Communicating Through Job Events

JDL events are how the server communicates job state transitions to your job. The required job_started_event is always invoked when the job transitions to the starting state.

Likewise, all the other state transitions have JDL equivalents that can be optionally implemented in your job. For example, the joblet_completed_event is invoked when a joblet has transitioned to completed. You could implement joblet_completed_event to launch another job or joblet or send a custom event to a Client, another job, or another joblet.

You can also use your own custom events for communicating between Client, job, child jobs and joblets.

Every partition of a job (client, job, joblet, child jobs) can communicate directly or indirectly with any other partition of a job by using Events. Events are messages that are communicated to each of the job partitions. For example, a joblet running on a resource can send an event to the job portion running on the server to communicate the completion of a stage of operation.

A job can send an event to a Java Client signaling a stage completion or just to send a log message to display in a client GUI.

Every event carries a dictionary as a payload. You can put any key/values you want to fulfill the requirements of your communication. The dictionary can be empty.

For more information about events are invoked at the state transitions of a job, see Job and Section B.7, Joblet State Values.

3.8.1 Sending and Receiving Events

To send an event from a joblet to a job running on a server, you would input the following:

  1. The portion in the joblet JDL to send the event:

    self.sendEvent("myevent", { "message": "hello from joblet" } )
  2. The portion in job JDL to receive the event:

    def myevent(self,params):
        print "hello from myevent. params=",params

To send an event from a job running on the server to a client, you would input the following:

self.sendClientEvent("notifyClient", { "log" : "Web server installation completed" } )

In your Java client, you must implement AgentListener and check for an Event message.

For testing, you can use the zos run ... --listen option to print events from the server. For additional details about the sendEvent() and sendClientEvent() methods in the Job and Joblet documentation.

3.8.2 Synchronization

By default, no synchronization occurs on job events. However, synchronization is necessary when you update the same grid objects from multiple events.

In that case, you must put a synchronization wrapper around the critical section you want to protect. The following JDL script is how this is done:

1  import synchronize
2  def objects_discovered_event(self, params):
3      print "hello"
4  objects_discovered_event = synchronize.make_synchronized(objects_discovered_event)

Line 1 specifies to use the synchronization wrapper, which requires you to import the synchronize package.

Lines 2 and 3 provide the normal definition to an event in your job, while line 4 wraps the function definition with a synchronized wrapper.