ColCOWS_Node.hh

//===========================================================================//
//    
//    Description: ColCOWS Nodes
//    Filename: colcows/ColCOWS_Node.hh
//    Authors: Michael Dussere and Aurélien Esnard
//    
//===========================================================================//
//    
//    Copyright (C) 2003 INRIA and CNRS
//    
//    This library 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.
//    
//    This library 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 this library; if not, write to the Free Software
//    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
//    
//===========================================================================//


#ifndef __COLCOWS_NODE_HH__
#define __COLCOWS_NODE_HH__

//---------------------------------------------------------------------------//
#include "ColCOWS_Include.hh"
#include "ColCOWS_Debug.hh" 
//---------------------------------------------------------------------------//
#include "ColCOWS_NodeDesc.hh" 
#include "ColCOWS_WorkspaceDesc.hh" 
#include "ColCOWS_RemoteWorkspaceManager.hh" 
//---------------------------------------------------------------------------//

namespace CORBA {
  class ORB;
}

namespace ColCOWS {
  class NodeServant;
  struct IdlWorkspaceDesc;
  class EventHandler;
  class EventHandlerManager;
};

__COLCOWS_BEGIN__

//! associated timeout (sec)
const unsigned int  WAITING_TIMEOUT = 2;

//! associated timeout (sec)
const unsigned int  WAITING_RETRY = 10;

//===========================================================================//
//                          ColCOWS node class                               //
//===========================================================================//

//! ColCOWS Node class
/** 
 * The Node class is the front end of ColCOWS library, the one appearing in the user source code.
 * It manages the local CORBA object references and the workspace descriptions, local and remote.
 * The class provides the user with methods for controlling the workspace life-cycle (activation/deactivation,  
 * connection/disconnection) and for exploring the references of the local and remote workspaces.
 *
 * \todo Use separate classes for the management of the workspace descriptions
 * \todo Allow several event handlers to be connected
 */
class Node : public NodeDesc
{

  //=========== friend classes ===========//
  friend class NodeServant;

  //================================================//
  //=========== class standard interface ===========//

public:
  
  //! constructor
  Node();
  
  //! destructor
  virtual ~Node();

  //! create a new node, full details
  static Node * New( std::string ws_id, 
                     std::string ws_kind, 
                     std::string node_kind, 
                     unsigned long num_node, 
                     unsigned long max_descendant, 
                     unsigned long nb_nodes,
                     unsigned long num_father,
                     CORBA::ORB * orbp  ) ;

  //! create a new node, in hierarchy
  static Node * NewHierachical( std::string ws_id,
                                std::string ws_kind, 
                                unsigned long num_node, 
                                unsigned long nb_nodes, 
                                unsigned long base,
                                CORBA::ORB * orbp  ) ;

  //! create a new node, generical
  static Node * NewNode( std::string ws_id,
                         std::string ws_kind, 
                         std::string node_kind, 
                         unsigned long num_node,
                         unsigned long nb_nodes,
                         CORBA::ORB * orbp  ) ;
  
  //! create a new node, as proxy
  static Node * NewProxy( std::string ws_id,
                          std::string ws_kind, 
                          unsigned long nb_nodes,
                          CORBA::ORB * orbp  ) ;
  
  //! create a new node, as node
  static Node * NewPort( std::string ws_id,
                         std::string ws_kind, 
                         unsigned long num_node, 
                         unsigned long nb_nodes,
                         CORBA::ORB * orbp  ) ;

  //=========================================//
  //=========== public  interface ===========//
  //=========================================//
public:

  //! print self
  virtual void printself(std::ostream & stream, int indent = 0) const;  

  //====================================//
  //============ Interface =============//

  //============ Activation =============//

  //! activate this node
  /** Do not ensure the workspace is activated after the return nor the "onActivation" treatments are done. 
   *  Must call "waitActivation" 
   **/
  void activate( ) ;

  //! deactivate this node
  /** Ensure the workspace is deactivated and the "onDeactivation" treatments are done **/
  void deactivate( ) ;

  //! test if the collective node is activated
  inline bool isActivated() const { return _local_workspace->getActivated(); }

  //=========== Connection =============//

  //! connect a remote workspace identified with an ID and a Kind on the local NameService
  /** Ensure the workspace is connected and the "onConnection" treatments are done **/
  inline unsigned long connect( const std::string & ws_id, const std::string & ws_kind )
  { return connect( ws_id, ws_kind, std::string() ); }

  //! connect a remote workspace identified with an ID and a Kind on another NameService
  /** Ensure the workspace is connected and the "onConnection" treatments are done **/
  unsigned long connect( const std::string & ws_id, const std::string & ws_kind, const std::string & nameservice_str) ;

  //! disconnect a remote workspace
  /** Ensure the workspace is disconnected and the "onDisonnection" treatments are done **/
  void disconnect( unsigned long num_connection ) ;

  //! disconnect all the remote workspaces
  /** Ensure all the connection are closed and all the "onDisonnection" treatments are done **/
  void disconnectAll( ) ;

  //! test if a workspace named 'ws_id' of kind 'ws_kind' is connected and return its connection number
  bool isConnected( std::string ws_id, std::string ws_kind ) const ;

  //! test if a workspace with num_connection is connected and return its connection number
  inline bool isConnected( unsigned long num_connection ) const
  { return (_remote_workspace_manager->find(num_connection) != _remote_workspace_manager->end() ); }

  //! test if a workspace named 'ws_id' of kind 'ws_kind' is connected and return its connection number
  unsigned long getNumConnection( std::string ws_id , std::string ws_kind ) ;

  //! get a vector of connection numbers according to id or kind critera
  void getNumConnectionVec( std::vector<unsigned long> & num_connection_vec ,
                            std::string ws_id = "" , 
                            std::string ws_kind = "" ) ;

  //=========== Description =============//

  //! get size of a remote workspace
  unsigned long getRemoteNbNodes( unsigned long num_connection, std::string node_kind = "" );

  //! get id of a remote workspace
  std::string getRemoteWorkspaceID( unsigned long num_connection );

  //! get kind of a remote workspace
  std::string getRemoteWorkspaceKind( unsigned long num_connection );

  //! get a remote remote workspace description
  inline WorkspaceDesc * getRemoteWorkspace( unsigned int num_connection )
  { return _remote_workspace_manager->getRemoteWorkspace(num_connection); }

  //! get size of the local workspace
  inline unsigned long getLocalNbNodes( std::string node_kind = "" ) const 
  { return _local_workspace->getNbNodes( node_kind ); }

  //! get id of the local workspace
  inline std::string getLocalWorkspaceID( ) const 
  { return _local_workspace->getId( ); }

  //! get kind of the local workspace
  inline std::string getLocalWorkspaceKind( ) const 
  { return _local_workspace->getKind( ); }

  //! get the local workspace description
  inline WorkspaceDesc * getLocalWorkspace() { return _local_workspace; }

  //==========================================//
  //============ Events Handling =============//

public:

  //! add an event handler in the manager
  unsigned int addEventHandler( EventHandler * event_handler );

  //! remove an event handler from the manager
  void removeEventHandler( unsigned int key ); 

  //! remove an event handler from the manager
  void removeEventHandler( EventHandler * event_handler );

  //============ Activation =================//

  //! wait end of activation
  /** Ensure local onActivation treatments are done **/
  bool waitActivation( bool use_timeout = true ); 

  //! wait end of deactivation
  /** Ensure local onDeactivation treatments are done **/
  bool waitDeactivation( bool use_timeout = true );

  //=========== Connection ==================//

  //! wait the connection of a remote workspace
  /** Ensure local onConnection treatments are done **/
  unsigned long waitConnection( std::string ws_id, std::string ws_kind, bool use_timeout = true ); 

  //! wait the disconnection of all the remote workspace
  /** Ensure local onDisconnection treatments are done **/
  unsigned long waitAllDisconnection( bool use_timeout = true );

  //! wait the disconnection of a remote workspace
  /** Ensure local onDisconnection treatments are done **/
  unsigned long waitDisconnection( std::string ws_id, std::string ws_kind, bool use_timeout = true );

protected:

  //! treatment on the activation of the workspace
  void onActivation( const IdlWorkspaceDesc& ws_desc ) ;

  //! treatment on the deactivation of the workspace
  void onDeactivation( const IdlWorkspaceDesc& ws_desc ) ;

  //! treatment on the connection of a remote workspace
  void onConnection( unsigned long num_connection, const IdlWorkspaceDesc& ws_desc, bool initiator ) ;

  //! treatment on the disconnection of a remote workspace
  void onDisconnection( unsigned long num_connection ) ;

  //============================================//
  //=========== protected  interface ===========//
  //============================================//

protected:

  //=========== helpers ===========//

  static unsigned long calculNumFather(unsigned long min, unsigned long max, unsigned long num_child, unsigned long base);

  static unsigned long calculMaxDescend(unsigned long min, unsigned long max, unsigned long num_child, unsigned long base);
  

  //=======================================//
  //============== Accessors ==============//
public:
  
  //! get a pointer on the associated event handler
  inline EventHandlerManager * getEventHandlerManager() {return _event_handler_manager;}

  //! associate an event handler with the workspace
  void setEventHandlerManager(EventHandlerManager * event_handler_manager);

  //! get a remote remote workspace manager
  inline RemoteWorkspaceManager * getRemoteWorkspaceManager( ) { return _remote_workspace_manager; }

  //! get the ORB pointer
  inline CORBA::ORB * getORB( ) const { return _orbp;}

  //! set the ORB pointer
  inline void setORB( CORBA::ORB * orbp ) { _orbp = orbp;}

  //=======================================//
  //=========== internal fields ===========//
protected:
  
  //! Pointer on the ORB
  CORBA::ORB * _orbp;

  //! event handler
  EventHandlerManager * _event_handler_manager;

  //! Implementation of CORBA interface
  NodeServant * _node_servant;

  //! local workspace description
  WorkspaceDesc * _local_workspace;

  //! remote workspace manager
  RemoteWorkspaceManager * _remote_workspace_manager;

  //! boolean indicates the user activation treatements are terminated
  bool _fully_activated;

  //! event mutex
  pthread_mutex_t _event_mut;

  //! event condition variable
  pthread_cond_t _event_cond;

};

//===========================================================================//

//! standard output stream operator
std::ostream& operator <<(std::ostream& stream, const Node& _this);

__COLCOWS_END__

#endif // __COLCOWS_NODE_HH__

//===========================================================================//

/** \example TestClient.cc */
/** \example TestClient2.cc */
/** \example TestServer.cc */
/** \example TestClient2_MPI.cc */
/** \example TestServer_MPI.cc */

//===========================================================================//

// EOF

---