dimawo
Class MasterAgent

java.lang.Object
  dimawo.agents.AbstractAgent
      dimawo.agents.LoggingAgent
          dimawo.MasterAgent

All Implemented Interfaces:

ErrorHandler, MOSCallBack, Runnable

public abstract class MasterAgent
extends LoggingAgent
implements MOSCallBack

This class represents the Master Agent (MA). It implements the master process of a master/worker application. The Master Agent is instantiated by one, and only one, Distributed Agent (DA) part of the group of DAs implementing the same DiMaWo application (note that each DA is generally executed in a different process, each process being executed by a different computer). This potentially implies the solving of leader election problem in order to select the DA that will instantiate the MA.

The base MA provides common functionalities but requires some key elements of its behavior to be implemented. In general, MA's behavior is more or less as follows:

1. the MA temporizes in order to wait for all workers to be instantiated or waits for a given number of workers to be up. The instantiation of new workers is signaled through topology changes ("joins", see onTopologyChange(DAId, ChangeType)).
2. Initial data are provided to each worker through datagram messages or a broadcast.
3. The MA waits for all workers to finish their execution. It may have to control workers execution or centralize informations (beware of a bottleneck!).
4. After all workers have finished their execution, the MA ends the application by calling shutdown().

The common functionalities provided by the base implementation are:

• broadcasting of messages to all workers (see broadcastWorkerMessage(WorkerMessage, WorkerMessage))
• a shortcut to send datagram messages to workers (see sendMessage(WorkerMessage))
• the ability to shutdown the whole application i.e. terminate all processes running workers and the master itself (see shutdown()). The shutdown generally occurs after the detection of a fatal error or when the application successfully reached the end of its execution.

Following elements of the behavior of the MA must be implemented by the user:

• handling of user defined events and messages (see handleMasterEvent(Object) and handleUserDefinedAgentMessage(MasterMessage)).
• The behavior in case a worker ends its execution (see handleWorkerExit(WorkerExitMessage)).
• handling of topology changes (see onTopologyChange(DAId, ChangeType)).
• initialization of master's state and final operations executed before master ends its execution (see onStartup() and onExit() respectively).

The master implements following agent's behavior:

• In case an uncaught exception is submitted by a child agent, the whole application is interrupted.
• On agent's initialization, a message is logged and user's code is called.
• On agent's exit, user's code is called and a message is logged.

Author:

Gerard Dethier

See Also:

DistributedAgent, be.ulg.montefiore.dimawo.middleware.WorkerAgent

Nested Class Summary

protected static class

MasterAgent.ChangeType This enumeration provides the types of topology changes.

Nested classes/interfaces inherited from class dimawo.agents.AbstractAgent

AbstractAgent.AgentState

Field Summary

Fields inherited from class dimawo.agents.AbstractAgent

agentName, errorHandler

Constructor Summary

MasterAgent(DistributedAgent hostingDa, String name)
Instantiates the Master Agent (MA) giving it a name and associating it to a DA.

Method Summary

protected void	broadcastWorkerMessage(WorkerMessage toLocal, WorkerMessage toRemote) Broadcasts a message to all workers.
DistributedAgent	getHostingDA() Returns the DA that instantiated the MA.
String	getWorkingDir() Returns the working directory of hosting DA.
protected void	handleChildException(UncaughtThrowable o) Causes the whole application to terminate its execution, potentially before completion.
protected void	handleDaError(DaError msg) Handles an error message sent by a DA.
protected abstract void	handleMasterEvent(Object o) Handles a user defined or unknown master event.
protected void	handleMessage(Object o) Handles a new message taken from the queue.
protected abstract void	handleUserDefinedAgentMessage(MasterMessage msg) Handles a received message that is not handled by base implementation.
protected void	handleUserDefinedMessageSent(Message msg) Handles a "message sent" event for a user defined sent message.
protected abstract void	handleWorkerExit(WorkerExitMessage msg) Handles a message indicating the end of the execution of a worker.
protected void	init() Implements the operations to be executed when agent enters INIT state.
protected void	logAgentExit() Implements the operations to be executed when logging agent enters STOPPED state.
protected abstract void	onExit() Called when Master Agent terminates its execution.
protected abstract void	onStartup() Called when Master Agent (MA) is initialized i.e. directly after the agent is started and before any message is handled.
protected abstract void	onTopologyChange(DAId subject, MasterAgent.ChangeType type) Called when the Master Agent (MA) handles a message signaling a local change in DA's topology (i.e. a new DA joined or a DA left the overlay).
protected void	sendMessage(WorkerMessage msg) Sends a message to a worker agent.
protected void	shutdown() Terminates the execution of the application.
void	signalBroken(BrokenDA bda)
void	signalSent(Message m, boolean success) Signals that a message was successfully sent or an error occurred and the message could not be sent.
void	submitMasterMessage(MasterMessage m) Inserts a MasterMessage message in MA's message queue.

Methods inherited from class dimawo.agents.LoggingAgent

exit, getFilePrefix, setPrintStream

Methods inherited from class dimawo.agents.AbstractAgent

agentPrintMessage, agentPrintMessage, agentPrintMessage, flushPendingMessages, getDefaultVerbosityLevel, getState, getVerbosityLevel, join, join, run, setAgentName, setDaemon, setDefaultVerbosityLevel, setErrorHandler, setPrintStream, setVerbosityLevel, signalChildError, start, stop, submitError, submitMessage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MasterAgent

public MasterAgent(DistributedAgent hostingDa,
                   String name)

Instantiates the Master Agent (MA) giving it a name and associating it to a DA.

Parameters:

hostingDa - The DA that instantiates the MA.

name - The name of the MA.

Method Detail

getHostingDA

public DistributedAgent getHostingDA()

Returns the DA that instantiated the MA.

Returns:

The DA that instantiated the MA.

submitMasterMessage

public void submitMasterMessage(MasterMessage m)
                         throws InterruptedException

Inserts a MasterMessage message in MA's message queue.

Throws:

InterruptedException - Thrown if executing thread is interrupted during a blocking insertion (happens when message queue is full).

getWorkingDir

public String getWorkingDir()

Returns the working directory of hosting DA.

Returns:

The working directory of hosting DA.

logAgentExit

protected void logAgentExit()

Description copied from class: LoggingAgent

Implements the operations to be executed when logging agent enters STOPPED state.

Specified by:

logAgentExit in class LoggingAgent

See Also:

AbstractAgent.exit()

init

protected void init()
             throws Throwable

Description copied from class: AbstractAgent

Implements the operations to be executed when agent enters INIT state.

Specified by:

init in class AbstractAgent

Throws:

Throwable - If an error occurred during initialization.

handleMessage

protected void handleMessage(Object o)

Description copied from class: AbstractAgent

Handles a new message taken from the queue.

Specified by:

handleMessage in class AbstractAgent

Parameters:

o - A message.

handleChildException

protected void handleChildException(UncaughtThrowable o)
                             throws AgentException

Causes the whole application to terminate its execution, potentially before completion.

Overrides:

handleChildException in class AbstractAgent

Parameters:

o - The error.

Throws:

AgentException - If the agent does not have an error handler.

shutdown

protected void shutdown()

Terminates the execution of the application. All processes executing a worker will eventually terminate their execution.

sendMessage

protected void sendMessage(WorkerMessage msg)

Sends a message to a worker agent.

Parameters:

msg - The message to send to the worker agent.

signalSent

public void signalSent(Message m,
                       boolean success)

Description copied from interface: MOSCallBack

Signals that a message was successfully sent or an error occurred and the message could not be sent.

Specified by:

signalSent in interface MOSCallBack

Parameters:

m - The message.

success - A boolean indicating if the message was successfully sent or an error occurred. If success is true, the message was successfully sent. An error occurred otherwise.

signalBroken

public void signalBroken(BrokenDA bda)

Specified by:

signalBroken in interface MOSCallBack

broadcastWorkerMessage

protected void broadcastWorkerMessage(WorkerMessage toLocal,
                                      WorkerMessage toRemote)

Broadcasts a message to all workers. Two copies of the message to send must be provided: one for local worker (i.e. the worker instantiated by the same DA as master) and one for remote workers. This is required because the message for local worker is transmitted through DA and not through the Communicator like remote workers' message.

Parameters:

toLocal - The message copy to transmit to local worker.

toRemote - The message copy to transmit to remote workers.

handleDaError

protected void handleDaError(DaError msg)

Handles an error message sent by a DA. This kind of message is sent by a DA when it is about to terminate its execution because of a fatal error. The reception of this message causes the master to terminate the execution of the whole application.

Parameters:

msg - The error message.

handleUserDefinedMessageSent

protected void handleUserDefinedMessageSent(Message msg)
                                     throws Exception

Handles a "message sent" event for a user defined sent message.

Parameters:

o - The "message sent" event.

Throws:

Exception - If an error occurred during event's handling.

See Also:

handleMessageSent(MessageSent)

handleUserDefinedAgentMessage

protected abstract void handleUserDefinedAgentMessage(MasterMessage msg)
                                               throws Exception

Handles a received message that is not handled by base implementation. A message that is not handled by base implementation is either a user defined message or an unexpected message (in this case, an exception is thrown).

Parameters:

msg - The message to handle.

Throws:

Exception - If an error occurred during message handling.

handleWorkerExit

protected abstract void handleWorkerExit(WorkerExitMessage msg)
                                  throws Exception

Handles a message indicating the end of the execution of a worker. This kind of message is sent by a DA to signal the worker it instantiated has terminated its execution. The message contains the result the worker may have produced. The DA continues its execution until the whole application is terminated.

Parameters:

msg - The message indicating the end of the execution of a worker.

Throws:

Exception - If an error occurred during the handling of the message.

See Also:

WorkerExitMessage.getResult()

onExit

protected abstract void onExit()

Called when Master Agent terminates its execution. This method should essentially contain "clean-up" operations.

onStartup

protected abstract void onStartup()
                           throws Throwable

Called when Master Agent (MA) is initialized i.e. directly after the agent is started and before any message is handled.

Throws:

Throwable - If an error occurs during MA's initialization.

onTopologyChange

protected abstract void onTopologyChange(DAId subject,
                                         MasterAgent.ChangeType type)
                                  throws Exception

Called when the Master Agent (MA) handles a message signaling a local change in DA's topology (i.e. a new DA joined or a DA left the overlay).

Parameters:

subject - The DA that joined or left the overlay.

type - The type of topology change (join, leave).

Throws:

Exception - If an error occurred during event handling.

handleMasterEvent

protected abstract void handleMasterEvent(Object o)
                                   throws Exception

Handles a user defined or unknown master event.

Parameters:

o - The event.

Throws:

Exception - If an error occurred during event handling.