AddressClient.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
/*! \file AddressClient.h
*  \brief Declares the class that communicates with an address server.
*  \author $Author: rsharo $
*  \version $Revision: 1.1 $
*  \date    $Date: 2004/04/07 13:45:04 $
*///////////////////////////////////////////////////////////////////////////////
#ifndef ADDRESS_CLIENT_H
#define ADDRESS_CLIENT_H

#include "ace/INET_Addr.h"
#include "ace/SOCK_Dgram.h"
#include "ace/Reactor.h"

#include "ace/Synch_T.h"

#include <map>
#include <list>
#include <vector>

#include "Comm/ReplyQueue.h"

//
// A reactor-based class that knows how to communicate with an AddressServer.
//
// This class is a fundamental part of the MessageClient/MessageServer scheme.
// Message clients are user-derived classes that send and receive messages
// on the network. Message clients carry an integer identifier that
// determines which messages they are to receive.  Since clients can be
// distributed over a network, a means is needed to keep track of which
// message clients are at which IP addresses -- or more specifically which
// IP addresses are interested in which messages.
// An address server is an object that holds the mappings from message ID
// to IP address (called bindings). The address server will typically
// be located at a multicast address so it can be physically located anywhere
// on the network.
//
// AddressClient is a class that manages communication with the address server.
// Through AddressClient method calls, bindings can be queried, added or
// removed from an address server.  A message server depends on its
// AddressClient to route incoming and outgoing messages.
//
// The AddressClient class is a subclass of ACE_Event_Handler, and must
// be registered with an ACE_Reactor to function properly.
class AddressClient : public ACE_Event_Handler
{
public:
        //
        // The data type that hold a list of IP addresses.
        typedef std::vector<ACE_INET_Addr>                              AddrList_t;

        //
        // Constructor. 
        // Given the IP address of the address server, this
        // method constructs an AddressClient.  The client
        // must be registered with a reactor before it will be useful,
        // however.
        explicit AddressClient (const ACE_INET_Addr &addrServer);

        //
        // Destroys the AddressClient.  The client should have been
        // deregistered from its reactor (if any) before this method
        // is called.
        ~AddressClient (void);

        //
        // Connect this object to a reactor.
        // This must be done before any server communication is initiated.
        // Returns zero on success and -1 on failure.
        int RegisterWithReactor(ACE_Reactor &theReactor);

        //
        // Disconnects this object from the reactor.
        // This effectively disables the AddressClient.  This method
        // should be called before destroying the object.
        // The "immediate" flag determines whether the call should
        // return immediately or not.  If set to false, then the
        // AddressClient will attempt to remove itself from the 
        // AddressServer's notification list. The "immediate" flag
        // will typically only be set if the client needs to shut
        // down quickly or if the AddressServer is shutting down as well.
        // Returns zero on success and -1 on failure.
        int RemoveFromReactor(ACE_Reactor &theReactor, bool immediate=false);

        //
        // Sets the amount of time a server call will wait
        // before giving up and reporting an error. A value of zero
        // means "wait forever".
        void SetTimeout(const ACE_Time_Value &tv);

        //
        // Queries the server to see if it is responding.
        // The client will wait up to its specified timeout interval
        // before returning a failure.
        // Returns zero on success and -1 on failure.
        int PingServer();

        //
        // Registers the AddressClient to be notified when the server's
        // bindings change. This is necessary to know when to invalidate
        // the AddressClient's cache. This method should be called one time
        // after the AddressClient is registered with the reactor, but before
        // any bindings are requested.
        int RegisterServerCallback();

        //
        // Removes the AddressClient from the AddressServer's notification list.
        // The AddressClient will no longer be notified when the server's
        // bindings change. This method is automatically called from 
        // RemoveFromReactor() unless the "immediate" flag was set.
        // Calling this method is typically a precursor to shutdown.
        // Returns zero on success and -1 on failure.
        int RemoveServerCallback();

        //
        // Clears the AddressServer's notification list.
        // No AddressClient objects will be notified any longer when
        // the server's bindings change. Note that this method does not
        // notify the other AddressClients that this has happened.
        // This method would typically only be called when the AddressServer
        // is to be reset from an indeterminate state (such as after a restart)
        // and all other clients have been shut down.
        // Returns zero on success and -1 on failure.
        int ClearServerCallbacks();

        //
        // Retrieves a list of IP addresses bound to a given message ID.
        // The MessageServer will call this method any time a message
        // is sent.  Messages destined for a given ID will be routed
        // to each IP address in the binding list.
        // Returns zero on success and -1 on failure.
        int GetBindings(u_int dest, AddrList_t &theList);

        //
        // Adds an IP address/ID binding to the AddressServer.
        // This method is called when a MessageClient is added to the
        // MessageServer with a previously-unused ID. The AddressServer
        // will add the IP address from the binding string to its list
        // of addresses for the given ID.
        // The binding string is of standard ACE format:
        //    "<hostname>:<port>"
        // Returns zero on success and -1 on failure.
        int AddBinding(u_int id, const char *binding);

        //
        // Removes an IP address/ID binding from the AddressServer.
        // This method is called when a MessageClient is removed from the
        // MessageServer and the ID is otherwise-unused. The AddressServer
        // will remove the IP address from the binding string from its list
        // of addresses for the given ID.
        // The binding string is of standard ACE format:
        //    "<hostname>:<port>"
        // Returns zero on success and -1 on failure.
        int RemoveBinding(u_int id, const char *binding);

        //
        // Clears all IP address/ID bindings from the AddressServer.
        // This method would typically only be called when the AddressServer
        // is being reset from an indeterminate state (such as after a restart)
        // and no MessageClients are currently registered.
        // Returns zero on success and -1 on failure.
        int ClearBindings();
        
        //
        // Implementation of the handle_input() method derived from
        // ACE_Event_Handler.  This method processes messages sent from the
        // address server.
        virtual int                     handle_input (ACE_HANDLE fd);   

        //
        // Implementation of the get_handle() method derived from
        // ACE_Event_Handler.  This method returns a handle to the AddressClient's
        // UDP socket.
        virtual ACE_HANDLE      get_handle (void) const;

protected:

        //
        // The data structure used to hold cached bindings.
        typedef std::map<u_int, AddrList_t>                             BindMap_t;
        //
        // The internal structure that holds individual binding pairs.
        typedef BindMap_t::value_type                                   BindValue_t;

        //
        // The data type of the queue used to serialize the replies
        // expected after AddressServer commands.
        typedef ReplyQueue<std::string, ACE_SYNCH>              ReplyQueue_t;

        //
        // Sends a command to the AddressServer via UDP/IP.  Note that all
        // AddressServer commands are in the form of ASCII strings. If a reply
        // is received before the AddressClient's timeout period expires,
        // it is placed in the "reply" argument.
        // Returns zero if command was send and a reply was received within
        // the timeout period, -1 otherwise.
        int SendCommand(const char *str, std::string &reply);
                
private:
        ACE_INET_Addr                                                                   m_addrServer;

        char                                                                                    m_buf[BUFSIZ];
        ACE_SOCK_Dgram                                                                  m_socket;

        ACE_Thread_Mutex                                                                m_bindingMutex;
        BindMap_t                                                                               m_bindings;

        ACE_Thread_Mutex                                                                m_pendingReplyMutex;
        ReplyQueue_t                                                                    m_pendingReplyQueue;

        long                                                                                    m_notificationID;

        ACE_Thread_Mutex                                                                m_pingMutex;
        ACE_Thread_Condition<ACE_Thread_Mutex>                  m_pingCondition;

        ACE_Time_Value                                                                  m_timeout;
};

#endif // ADDRESS_CLIENT_H

---