[omniORB-dev] ImR idl proposal

kendall bailey kendall@drakealumni.net
Wed, 22 Jan 2003 03:55:51 -0600


This is a multi-part message in MIME format.
--------------070002050106060109060005
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Attached is some IDL I've written which covers what I believe has been 
discussed as capabilities of the portable ImR for use with omniORB. 
 I've verified it compiles, but haven't implemented anything yet.  I'm 
putting this out for comment.

Kendall


--------------070002050106060109060005
Content-Type: text/plain;
 name="imr.idl"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="imr.idl"


#ifndef omni_implementation_repository_idl_
#define omni_implementation_repository_idl_

/**
* Interface of a portable implementation repository.
*/
module omniImR {

   typedef string Process_t;

   interface ProcessManager;
   interface LoadManager;

   //------------------------------------------------------------
   exception UnknownName {
      string name;
   };

   //------------------------------------------------------------
   exception WrongProcess {
   };

   //------------------------------------------------------------
   exception DuplicateName {
      string name;
   };

   //------------------------------------------------------------
   exception BadRegex {
   };

   //------------------------------------------------------------
   typedef sequence<string> string_list;

   //------------------------------------------------------------
   /**
   * defines a name/value pair where the value is
   * a numeric measure of some load
   */
   struct LoadInfo
   {
      string metric;
      double value;
   };
   typedef sequence<LoadInfo> LoadInfo_list;

   //------------------------------------------------------------
   /** 
   * defines a simple 1:N mapping of pysical process name to
   * logical program names.  It's likely each program name will
   * correspond to a POA name.  If a process is thought to be
   * running, it's manager is included, otherwise it is nil.
   */ 
   struct ProgramMapping {
      string          process_name;
      ProcessManager  manager;
      string_list     program_names;
   };

   typedef sequence<ProgramMapping> ProgramMapping_list;

   //------------------------------------------------------------
   /**
   * defines a single member of a replica group.
   */  
   struct GroupMember {
      ProcessManager manager;
      string         program;
      Object         ref;
   };

   typedef sequence<GroupMember> Group_list;

   //------------------------------------------------------------
   /**
   * defines a complete group of replicas
   */
   struct GroupMapping {
      string         group_name;
      Group_list     members;
   };
   typedef sequence<GroupMapping> GroupMapping_list;

   //------------------------------------------------------------
   /**
   * Allows administration of the ImR.
   */
   interface ImplementationRepositoryAdmin {

      /** 
      * Make the ImR aware of a physical process that it can
      * potentially start/stop.
      *
      * start_command may have a @imr_ior@ token where
      * the ImR can plug in it's own IOR on the command line.
      *
      * stop_command may have a @pm_ior@ token where the
      * ProcessManager's ior is placed.
      */
      void 
      registerProcess( 
         in string process_name,
         in string start_command,
         in string stop_command )
            raises( DuplicateName );

      /** add a logical program to a physical process.
      * This tells the ImR that when requests come in for
      * the given program, it should ensure the associated 
      * process is started
      */
      void 
      addProgramToProcess( 
         in string process_name,
         in string program_name )
            raises( DuplicateName );

      /**
      * Permenantly remove a program from a process.  This
      * should be done prior to adding the same program to 
      * another process.
      */
      void
      removeProgramFromProcess(
         in string process_name,
         in string program_name )
            raises( UnknownName );

      /**
      * Generate a persistent reference.  It's not necessary
      * for the process or program to be registered in advance.
      * This just generates an appropriate reference for future use
      * without adding to the persistent state of the ImR at all.
      */
      Object
      generatePersistent(
         in string program_name,
         in string object_name);

      /**
      * Find all processes which match the expression and return
      * all mappings of process -> programs.  The format of the
      * regular expression is an implementation detail.  For example,
      * if the the ImR is implemented in Python, then the Python re 
      * module may be used to match program names.  In any case, an
      * empty string should return the complete process list.
      * note: an iterator based method may be needed here too, if the
      *       returned list may get very large.
      */
      ProgramMapping_list
      getMappings(
         in string process_name_exp)
            raises( BadRegex );

    
      /**
      * Find all processes which have a program which matches the
      * expression.  See getMappings() above.  Each ProgramMapping
      * instance should have only those program names which match
      * the expression listed in the program_names field.  To get
      * full listings, use getMappings().  An empty expression 
      * should return all of the mappings.
      * note: an iterator based method may be needed here too.
      */
      ProgramMapping_list 
      getProcesses(
         in string program_name_exp)
            raises( BadRegex );

      /**
      * Returns the groups which match the expression.
      * An empty expression should return all groups.
      */
      GroupMapping_list
      getGroups(
         in string group_name_exp)
            raises( BadRegex );
   };

   //------------------------------------------------------------
   interface ImplementationRepository {
      /** 
      * Upon startup, a process should register.
      * The ImR returns a process_id that the process should
      * use to identify itself with each request.
      */
      Process_t 
      rebindProcess(
         in string         process_name,
         in ProcessManager manager );

      /**
      * Notify the ImR that the process is shutting down
      */
      void
      unbindProcess(
         in Process_t      process_id);

      /**
      * Returns an indirect reference for an object hosted
      * by the named program.  The program must already be
      * registered with the process.  The process
      * calling this must have notified the ImR that it started
      * and supply the ImR assigned process_id.
      *
      * An ImR implementation is free to handle URI's
      * of the form corbaloc::<host>:<port>/<program_name>#<obj_name>
      * but it isn't required.
      */ 
      Object 
      makePersistent( 
         in Process_t process_id,
         in string program_name,
         in string obj_name )
            raises( UnknownName, WrongProcess );

      /**
      * Tells the ImR that a specific object is part of a group of
      * replicas.  If the group doesn't already exist, it will be 
      * created.  The indirect reference returned will utilize load
      * balancing mechanisms when selecting a member of the group.
      * Group names need to be globally unique, not just within a program
      * since group members will naturally reside in multiple programs.
      */
      Object
      addToPersistentGroup(
         in Process_t process_id,
         in string program_name,
         in string group_name,
         in Object ref)
            raises( UnknownName, WrongProcess );
   };

   //------------------------------------------------------------
   /** An interface that the ImR uses to manage a running
   * process.  When a process starts, it should supply one of these
   * to the ImR to enable redirection of requests.
   */ 
   interface ProcessManager {
      /** When handling an indirect reference, the ImR uses
      * this to find the direct reference.
      Object
      getDirectReference(
         in string program_name,
         in string object_name) 
            raises (UnknownName);

      /** Each process is assigned an temporary id when it
      * starts.  This should return that id.
      */
      string 
      getProcessId();

      /** 
      * Each process must return a LoadManager (or nil if it 
      * doesn't support load balancing) so the ImR can make
      * load balancing decisions.
      */
      LoadManager
      getLoadManager();

      /**
      * return a platform dependent description of the processes
      * identity.  This could be as simple as a pid, or as complex
      * as the result of a detailed Unix "ps" command.
      * Recommended is something like: <host> <pid> <cmd>
      * example: "123.456.7.8 1345 myServer"
      * This makes it easy for tools to show info about all running processes
      * that the ImR knows about.
      */
      string getProcessInfo();
   };

   /**
   * An interface for gathering load information.
   * some info may be process specific, and some may be host
   * specific.  
   */
   interface LoadManager {
      /**
      * get a name for the host.  There may be multiple load managers
      * to a host, and some load data may need to be collected only
      * once from a particular host.  This name allows the ImR to 
      * avoid redundant load queries.
      */ 
      string
      getHostName();

      /** 
      * The ImR will query the LoadManager for a measure of some
      * metrics.  The LoadManager is responsible for returning
      * as many as it knows how to in a timely manner.
      * The ImR implementation will determine what metrics are
      * important and which are process vs. host level metrics.
      */
      LoadInfo_list
      queryLoad(
         in string_list load_metrics );       
   };
};

#endif


--------------070002050106060109060005--