MultiSRPC.H

Go to the documentation of this file.

// Copyright (C) 2001, Compaq Computer Corporation
// 
// This file is part of Vesta.
// 
// Vesta is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// 
// Vesta is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
// 
// You should have received a copy of the GNU Lesser General Public
// License along with Vesta; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

// Last modified on Sun May 22 22:53:25 EDT 2005 by ken@xorian.net   
//      modified on Fri Aug 14 15:32:04 PDT 1998 by mann   
//      modified on Mon Jun 16 11:07:42 PDT 1997 by heydon 
//      modified on Sun Aug 20 08:51:54 PDT 1995 by levin 

// MultiSRPC -- a cache of SRPC connections to servers on various machines

// A "MultiSRPC" object is a cache of client SRPC connections to
// potentially multiple servers that all export the same interface.
// The object provides two functions, Start and End.  A client calls
// Start and specifies the desired host for the server; Start returns
// a suitable SRPC object, either from its cache or newly created.
// The client calls End to tell MultiSRPC that it is finished with an
// SRPC connection, which is then placed in the cache for future use
// by Start.

// Each MultiSRPC object represents a cache for a collection of
// servers for the same interface.  Here the term "interface" is used
// somewhat loosely, since SRPC supports only a weak notion of
// interface.  SRPC allows its callers to specify a TCP port number
// (or name for a port number) that is used to connect client and
// server, but it is the responsibility of client and server code to
// agree on such a number through other means.

// There are two common styles of assigning port numbers.  In the
// simpler case, a port number is associated with an abstract
// "service" in advance of its deployment.  This number is either
// wired into the code of client and server, or is placed in some
// external configuration database where it is looked up by using some
// other piece of statically shared information.  This technique works
// well when the set of services can be enumerated in advance of
// execution.

// A more complicated scheme is used when the service is, in effect,
// an object, and the number of objects and/or their distribution
// across service machines is not known statically.  In this case, the
// port number is assigned dynamically and communicated between client
// and servers by means external to SRPC.  This technique allows
// multiple object servers to reside on the same host machine; they
// simply use different port numbers.

// MultiSRPC supports both of these styles.  An "interface" (port
// number) can be specified at construction time, in which case all
// cached connections held by the object use the same port number.
// Alternatively, the interface need not be specified at construction
// time, in which case the client must specify a port number on each
// call to Start.


#ifndef _MULTI_SRPC_H
#define _MULTI_SRPC_H

#include <Basics.H>
#include "SRPC.H"

class MultiSRPC {
public:
  // Constructors
  MultiSRPC(const Text &interface = Text(""));
  /* Make a new, empty cache for connections to servers.  If "interface" is
     non-empty, the servers all must export it.  If "interface" is empty,
     the choice of interface is made at the time Start is called. */

  // Destructor
  ~MultiSRPC();

  typedef int ConnId;
  /* A connection identifier is ``valid'' iff it is non-negative. */

  // Request a new SRPC connection to a particular server
  ConnId Start(const Text &hostname, SRPC*& srpc) throw (SRPC::failure)
    { return Start(hostname, "", srpc); };
  /* Return the valid identifier of a dedicated SRPC connection to a server
     for the interface named in the constructor running on the machine named
     "hostname", and set "srpc" to a pointer to the underlying connection.
     When done with the connection, either call "End" to make the connection
     available to other clients, or call "Discard" to cause the connection
     to be closed.

     Throws "SRPC::failure" if the interface name specified in the
     constructor was empty or if "hostname" is an unknown host or if
     that host is not currently exporting the interface named in the
     constructor. */

  ConnId Start(const Text &hostname, const Text &interface, SRPC*& srpc)
    throw(SRPC::failure);
  /* Return the valid identifier of a dedicated SRPC connection to a server
     for the specified interface on the specified hostname, and set "srpc"
     to a pointer to the underlying connection.  When done with the
     connection, either call "End" to make the connection available to other
     clients, or call "Discard" to cause the connection to be closed.

     Throws "SRPC::failure" if the constructor specified a non-empty
     interface name or if "hostname" is an unknown host or if that
     host is not currently exporting the specified "interface". */

  // Finish using a connection
  void End(ConnId id) throw();
  /* Make the connection "id" available to other clients. If "id" is invalid,
     this is a no-op. Otherwise, "id" must be a (valid) connection identifier
     returned by an invocation of the "Start" method above. */

  /* Usage Note: Since "End" is a no-op when "id" is an invalid connection
     identifier, no tests are required to handle the case where "Start" throws
     "SRPC::failure". Instead, clients can write code like this:

       MultiSRPC::ConnId id = -1;
       try {
           SRPC *srpc;
           id = multi.Start(hostname, srpc);
           // use "srpc" connection here
           multi.End(id);
       } catch (SRPC::failure) {
           multi.End(id);
           // handle failure
       }
  */

  void Discard(ConnId id) throw();
  /* Close the connection "id" and free the resources it consumed. Call this
     instead of End if you know the connection will not be useful to another
     client in the future.  If "id" is invalid, this is a no-op. */

  void Purge(const Text &hostname, const Text &interface) throw(SRPC::failure);
  /* If there are any cached SRPC connections to the specified interface on 
     the specified hostname that are not in use, close and discard them. */

private:
  // the server interface
  Text intf;

  // The connections are stored in a table indexed by server host name.
  // The entire table is protected by a mutex.
  Basics::mutex mu;

  // For now, the table is a simple array of entries. If the "srpc" entry is
  // NULL, then a failure was detected on some previous SRPC connection that
  // used this entry in the table, so the entry is available for a new
  // connection.  If the "interface" entry is Empty(), it is implicitly equal
  // to the value of "this->intf", which cannot be Empty().  
  struct Entry {
      Text hostname;
      Text interface;           // empty iff intf is non-empty
      bool inUse;               // connection in use?
      SRPC *srpc;               // NULL means this entry is not used

      // default constructor/destructor
      Entry() throw () : inUse(false), srpc((SRPC *)NULL) { /*SKIP*/ }
      ~Entry() throw ();
  };
  typedef Entry *EntryPtr;

  // The "tbl" is capable of holding "num" Entry's. The current entries are
  // "tbl[0]".."tbl[next-1]". All entries "tbl[next]".."tbl[num-1]" are NULL.
  int next, num;
  EntryPtr *tbl;
};

#endif // _MULTI_SRPC_H

---