osl.manager
Class ActorManager

java.lang.Object
  |
  +--osl.manager.ActorManager
Direct Known Subclasses:
BasicActorManager
public abstract class ActorManager
extends java.lang.Object
implements RemoteActorManager

This abstract class defines the basic methods necessary for implementing an actor manager. An actor manager is responsible for providing the basic actor services (e.g. sending messages, or creating other actors) to a collection of local actors. Moreover, a manager shields its local actors from interactions with external entities. That is, all interactions with local actors must go through the actor manager.

The ActorManager class is also expected to implement the RemoteActorManager interface which defines the mechanism by which external entities (except for actors) interact with a local actor manager. Typically, the RemoteActorManager interface is passed as the client interface for any RequestHandler sessions opened by an actor manager. Each actor manager also has an ActorManagerName which uniquely defines the manager relative to all other managers in the system (or at least relative to all other actor managers using the same implementation). An actor manager's name is used by other actor managers or local actors to request location-specific services such as remote creation or migration.

Version:
$Revision: 1.7 $ ($Date: 1999/01/19 18:43:32 $)
See Also:
Actor, ActorManagerName, RemoteActorManager, Scheduler, RequestHandler

Constructor Summary
ActorManager()
           
 
Method Summary
protected abstract  ActorName actorCreate(ActorImpl caller, ActorCreateRequest request)
          This method is called by a local actor implementation to request the creation of a new actor.
protected abstract  void actorFatalError(ActorImpl caller, java.lang.Exception e)
          This method is called by an actor implementation to report that it has encountered a fatal error.
protected abstract  java.lang.Object actorInvokeService(ActorImpl caller, ServiceName serviceName, java.lang.String meth, java.lang.Object[] serviceArgs)
          This method is called by a local actor in order to access a locally provided node service.
protected abstract  void actorMigrate(ActorImpl caller, ActorManagerName where)
          This method is called by a local actor that wishes to be migrated to another manager.
protected abstract  void actorSend(ActorImpl caller, ActorMsgRequest message)
          This method is called by a local actor to send a message to another actor.
protected  void implDeliver(ActorImpl actor, ActorMsgRequest msg)
          Deliver a message to an actor implementation.
protected  ActorName implGetName(ActorImpl actor)
          Return the name associated with an actor implementation.
protected  void implInitialize(ActorImpl actor, ActorName you, ActorCreateRequest req)
          Call the initialization method of an actor implementation.
protected  void implPostMigrateRebuild(ActorImpl actor, ActorManager ourMgr)
          Instruct an actor implementation to rebuild itself after a migration.
protected  void implStamp(ActorImpl actor, ActorMsgRequest msg)
          Instruct an actor implementation to stamp a message.
abstract  void managerInitialize(Scheduler S, RequestHandler R)
          Initialize a new actor manager.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ActorManager

public ActorManager()
Method Detail

managerInitialize

public abstract void managerInitialize(Scheduler S,
                                       RequestHandler R)
                                throws RequestException
Initialize a new actor manager. This method should be called before the actor manager is used to manage a collection of actors.

Parameters:
S - The Scheduler instance which should be used to schedule all threads required by the manager. Most of these threads will correspond to actors. Thus, it is advantageous to use a scheduler customized to efficiently handle actors.
R - The RequestHandler instance which should be used for interactions between this manager and other managers in the system.
Throws:
RequestException - Thrown if an error is encountered while opening a new RequestHandler session.

implInitialize

protected void implInitialize(ActorImpl actor,
                              ActorName you,
                              ActorCreateRequest req)
                       throws java.lang.Exception
Call the initialization method of an actor implementation.
Parameters:
you - The ActorName that should be used as the name of the new actor.
rtClass - The run-time Class of the user-written actor that should be instantiated by this implementation. This class will always be an extension of the Actor class.
initArgs - The array of arguments to pass to the constructor of the user-defined actor when it is instantiated.
Throws:
java.lang.Exception - The actual type of exception thrown depends on the implementation being used.

implDeliver

protected void implDeliver(ActorImpl actor,
                           ActorMsgRequest msg)
Deliver a message to an actor implementation.
Parameters:
actor - A reference to the ActorImpl which receive the message.
msg - The ActorMsgRequest structure to be delivered. This structure must be maintained by the actor as it is required if an exception is returned to the manager.

implGetName

protected ActorName implGetName(ActorImpl actor)
Return the name associated with an actor implementation. This is a protected field defined in ActorImpl, thus the need for the function definition here.
Parameters:
actor - A reference to the ActorImpl who's name should be returned.

implPostMigrateRebuild

protected void implPostMigrateRebuild(ActorImpl actor,
                                      ActorManager ourMgr)
Instruct an actor implementation to rebuild itself after a migration.
Parameters:
actor - The actor to rebuild.
ourMgr - A reference to the new manager of the implementation after migration has occurred.

implStamp

protected void implStamp(ActorImpl actor,
                         ActorMsgRequest msg)
Instruct an actor implementation to stamp a message.
Parameters:
actor - The actor to do the stamping.
msg - The message to be stamped.

actorCreate

protected abstract ActorName actorCreate(ActorImpl caller,
                                         ActorCreateRequest request)
                                  throws java.lang.SecurityException,
                                         RemoteCodeException
This method is called by a local actor implementation to request the creation of a new actor. The type of the new actor, the type of implementation that should encapsulate the new actor, the node it should be created on, as well as the arguments that should be passed to its constructor are encapsulated in the request structure. The name of the new actor is returned as the result of this call. Semantically speaking, once this method completes, the returned name is henceforth a valid target for receiving messages. As a side-effect, the ID field of the request argument is assigned a value unique relative to all other local requests. This value may be used to disambiguate any asynchronous exceptions caused by this request.

If an exception is thrown by this method (asynchronously or otherwise) then the returned actor name is no longer valid and any messages sent to it will be discarded. Furthermore, if the asynchronous exception resulted from the constructor invoked for the new actor, then any messages sent will be dropped. The following asynchronous exceptions may be thrown:

Parameters:
request - The ActorCreateRequest structure which describes the new actor to be created.
Returns:
The ActorName of the newly created actor.
Throws:
java.lang.SecurityException - Thrown if the class of new requested actor is not a subclass of Actor, or if the class of the new requested actor implementation is not a subclass of ActorImpl.
RemoteCodeException - Thrown for any other error encountered while attempting to perform the create. Note that this error may also be thrown asynchronously (e.g. when performing a remote create).

actorSend

protected abstract void actorSend(ActorImpl caller,
                                  ActorMsgRequest message)
                           throws RemoteCodeException
This method is called by a local actor to send a message to another actor. The sender and receiver of the message, as well as the method to invoke and any arguments to pass are encapsulated in the message structure. Note that all messages are sent asynchronously so that method completion does not indicate message delivery. As a side-effect, the ID field of the message argument is assigned a value unique relative to all other local requests. This value may be used to disambiguate any asynchronous exceptions caused by this request.

If an exception is returned by this method then the message structure is never sent. For asynchronous exceptions, only the RemoteCodeException corresponds to a message structure which should be viewed as "delivered". All other asynchronous exceptions should be interpreted as indicating that the original message structure was never sent. The following asynchronous exceptions may be thrown:

  • NoSuchMethodException - Thrown if no method matching the target method and arguments can be found in the target actor.
  • IllegalTargetException - Thrown if the target actor name is not legal. This may be because a sender attempted to spoof the name.
  • RemoteRequestRefusedException - Thrown if the manager which manages the target actor refuses the request to deliver the message.
  • RemoteCodeException - Thrown if the the target actor throws an exception while processing the message. In this case the message was delivered but the state of the actor depends on the exception thrown. For example, a fatal exception might indicate that the target actor is corrupted and has stopped processing messages.

Parameters:
message - The ActorMsg structure which indicates the sender and receiver of the message, the method to invoke on the receiver, and any arguments to pass to the target method.
Throws:
IllegalTargetException - Thrown if the target of the send is null or does not correspond to a legal actor name.
RemoteCodeException - Thrown for any other error encountered while attempting to perform the send. This usually indicates a local error in the manager implementation rather than an error encountered at the target of the message.

actorFatalError

protected abstract void actorFatalError(ActorImpl caller,
                                        java.lang.Exception e)
This method is called by an actor implementation to report that it has encountered a fatal error. Usually such an error means that the actor is no longer executable and should probably be removed from the system. The caller should pass an a reference to itself in order to be safely terminated by the manager.

Parameters:
thrower - The ActorImpl signalling the fatal error. Usually, this actor will be removed from the system.
e - The Exception which describes the fatal error encountered in the actor.

actorMigrate

protected abstract void actorMigrate(ActorImpl caller,
                                     ActorManagerName where)
                              throws IllegalNodeException,
                                     RemoteRequestRefusedException,
                                     RemoteCodeException
This method is called by a local actor that wishes to be migrated to another manager. The calling actor is migrated immediately, thus it is the responsibility of the underlying Actor implementation to ensure that the actor is in a consistent state before this method is called. Note that immediate migration will destroy the thread currently running in the actor. Once the migration is complete, the actor is restarted with a fresh thread. An exception returned by this method indicates that the actor was not migrated.

Parameters:
thrower - A reference to the ActorImpl which wishes to be migrated.
where - The ActorManagerName of the manager where this actor should be moved.
Throws:
IllegalNodeException - Thrown if the where argument does not correspond to a legal ActorManagerName.
RemoteRequestRefusedException - Thrown if the target manager of the migration refuses to accept the migrated actor.
RemoteCodeException - Thrown if the restart code after the migration throws an exception. The remote copy is destroyed in this case and the actor is treated as if it never migrated.

actorInvokeService

protected abstract java.lang.Object actorInvokeService(ActorImpl caller,
                                                       ServiceName serviceName,
                                                       java.lang.String meth,
                                                       java.lang.Object[] serviceArgs)
                                                throws ServiceNotFoundException,
                                                       ServiceException
This method is called by a local actor in order to access a locally provided node service. The name of the service must be specified together with any arguments required to correctly invoke the service. An arbitrary object is returned as a result of the service call. Note that Objects are used to specify both the service arguments as well as the return type so that very general services may be specified. It is up to the caller to correctly cast return values to their appropriate type.
Parameters:
serviceName - The ServiceName of the service to invoke.
serviceArgs - An Object which represents the sole argument to pass to the invocation function of the service.
Returns:
An Object representing the value returned by the service invocation.
Throws:
ServiceNotFoundException - Thrown if no instance of the named service can be found on this node.
ServiceException - Thrown if the service throws an exception while processing the request.