gzDistClient.h

Go to the documentation of this file.

//*****************************************************************************
// File         : gzDistClient.h
// Module       : gzDistribution
// Description  : Definition of gzDistClientInterface
// Author       : Christian Andersson
// Product      : GizmoDistribution 2.1.1
//      
// Copyright © 2004 - Saab Training Systems AB, Sweden
//          
// NOTE:    GizmoDistribution is a toolkit used for implementing distributed 
//          objects and events in C++
//
//
// Revision History...
//
// Who  Date    Description
//
// CAN  031021  Created file
//
//*****************************************************************************
#ifndef __GZ_DIST_CLIENT_H__
#define __GZ_DIST_CLIENT_H__

// Includes
#include "gzDistBase.h"
#include "gzDistNotification.h"
#include "gzDistServer.h"

//-------------------------- gzDistClientInterface ----------------------------

//*****************************************************************************
// Class    : gzDistClientInterface
//                                  
// Purpose  : The standard interface to derive your user class from
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// CAN  031021  Created 
//                                  
//*****************************************************************************

class gzDistClientInterface
{
    friend class gzDistSession;
    friend class gzDistManager;
    friend class gzDistClientThread;
    friend class gzDistClientThreadPool;

    public:


        GZ_DIST_EXPORT gzDistClientInterface(const gzString& clientName);


        GZ_DIST_EXPORT gzDistClientInterface(const gzDistClientInterface& original);


        GZ_DIST_EXPORT virtual ~gzDistClientInterface();


        GZ_DIST_EXPORT gzBool initialize(const gzDouble& tickInterval = 0, gzULong poolId = GZ_DIST_POOL_ID_DEFAULT, gzBool responseBoost = FALSE);


        GZ_DIST_EXPORT gzBool uninitialize(gzBool wait = FALSE);


        GZ_DIST_EXPORT gzBool isInitialized();


        GZ_DIST_EXPORT const gzDistClientID& getID();


        GZ_DIST_EXPORT gzDistSessionPtr getSession(const gzString& sessionName, gzBool create = FALSE, gzBool global = FALSE, gzDistServerPriority prio = GZ_DIST_SERVER_PRIO_NORMAL);


        GZ_DIST_EXPORT gzBool joinSession(const gzDistSessionPtr& session, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool resignSession(const gzDistSessionPtr& session, gzInt timeOut = GZ_DIST_SYNCHRONOUS);


        GZ_DIST_EXPORT gzBool subscribeSessions(gzBool notifyExisting = FALSE, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool unsubscribeSessions(gzInt timeOut = GZ_DIST_SYNCHRONOUS);


        GZ_DIST_EXPORT gzBool subscribeEvents(gzType* classType, const gzDistSessionPtr& session, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool unsubscribeEvents(gzType* classType, const gzDistSessionPtr& session, gzInt timeOut = GZ_DIST_SYNCHRONOUS);


        GZ_DIST_EXPORT gzBool sendEvent(gzDistEvent* event, const gzDistSessionPtr& session);


        GZ_DIST_EXPORT gzBool subscribeObjects(gzType* classType, const gzDistSessionPtr& session, gzBool notifyExisting = FALSE, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool unsubscribeObjects(gzType* classType, const gzDistSessionPtr& session, gzInt timeOut = GZ_DIST_SYNCHRONOUS);


        GZ_DIST_EXPORT gzBool subscribeAttributes(const gzDistObjectPtr& object, gzBool notifyExisting = FALSE, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool unsubscribeAttributes(const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_SYNCHRONOUS);


        GZ_DIST_EXPORT gzBool subscribeAttributeValue(const gzString& attributeName, const gzDistObjectPtr& object, gzBool notifyExisting = FALSE, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool subscribeAttributeValue(const gzDistObjectPtr& object, gzBool notifyExisting = FALSE, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool unsubscribeAttributeValue(const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool subscribeAttributeValue(const gzDistTransactionPtr& transaction, const gzDistObjectPtr& object, gzBool notifyExisting = FALSE, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool subscribeAttributeValue(const gzDistNotificationSet& attributes, const gzDistObjectPtr& object, gzBool notifyExisting = FALSE, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool unsubscribeAttributeValue(const gzString& attributeName, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_SYNCHRONOUS);


        GZ_DIST_EXPORT gzBool unsubscribeAttributeValue(const gzDistTransactionPtr& transaction, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool updateObject(const gzDistTransactionPtr& transaction, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool updateObject(const gzString& attributeName, const gzDynamicType& value, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool removeAttributes(const gzDistTransactionPtr& transaction, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool removeAttribute(const gzString& attributeName, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool addObject(const gzDistObjectPtr& object, const gzDistSessionPtr& session, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzDistObjectPtr findObject(const gzString& objectName, const gzDistSessionPtr& session);


        GZ_DIST_EXPORT gzDistObjectPtr waitForObject(const gzString& objectName, const gzDistSessionPtr& session, gzInt timeOut = 10);


        GZ_DIST_EXPORT gzBool removeObject(const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool requestOwnership(const gzString& attributeName, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool dropOwnership(const gzString& attributeName, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzBool pullOwnership(const gzString& attributeName, const gzDistObjectPtr& object, gzInt timeOut = GZ_DIST_ASYNCHRONOUS);


        GZ_DIST_EXPORT gzVoid setAccumulateTick(gzBool accumulate);

        /* Typically used at a shutdown situation to ensure that all data are processed before shutdown.
           \param outQueue  If outQueue is TRUE, the queue with messages from the client is verifyed.
                            If outQueue is FALSE, the queue with messages to the client is verifyed.
           \return          TRUE if there are any data, otherwise false.*/
        GZ_DIST_EXPORT gzBool hasPendingData(gzBool outQueue = TRUE);

        /* One of the purposes with gzDistCilentInterface is to create a single threaded environment.
           If you need to communicate directly to a client and still remain the single threaded environment in the client,
           you can invoke calls via the invoke method, and the call cill be marshalled to the client thread if the calling thread is 
           not the same as the "client thread".
           \invokeData  The data that should be passed to the client.
           \return      The return value from the client.
           \note        The return value is only valid if the synchronous is set to TRUE.
                        The client must be initialized to use this call.
           \sa          onInvoke(const gzDynamicType&)*/
        GZ_DIST_EXPORT gzDynamicType invoke(const class gzDistInvokeMessage& message, gzBool synchronous = FALSE);

    protected:


        virtual gzVoid onClientTick() {}


        virtual gzBool canProcessClientMessages() {return TRUE;}

        //----- notification callbacks -----
    

        virtual gzVoid onEvent(gzDistEvent* event) {}


        virtual gzVoid onNewObject(gzDistObject* object, gzDistSession* session) {}


        virtual gzVoid onRemoveObject(gzDistObject* object, gzDistSession* session) {}


        virtual gzVoid onUpdateAttributes(const gzDistNotificationSet& attributes, gzDistObject* object, gzDistSession* session) {}


        virtual gzVoid onNewAttributes(const gzDistNotificationSet& attributes, gzDistObject* object, gzDistSession* session) {}


        virtual gzVoid onRemoveAttributes(const gzDistNotificationSet& attributes, gzDistObject* object, gzDistSession* session) {}


        virtual gzVoid onNewSession(gzDistSession* session) {}


        virtual gzVoid onRemoveSession(gzDistSession* session) {}


        virtual gzVoid onGrantOwnership(const gzString& attributeName, gzDistObject* object, gzDistSession* session) {}


        virtual gzVoid onDropOwnership(const gzString& attributeName, gzDistObject* object, gzDistSession* session) {}


        virtual gzVoid onRequestOwnership(const gzString& attributeName, gzDistObject* object, const gzDistClientID& requester, gzDistSession* session) {}


        virtual gzVoid onSystemShutdown() {}


        virtual gzVoid onDebugMessage(class gzDistDebugNotification* notification) {}

        /*  \return The value that should be passed to the caller
            \sa invoke(const gzDynamicType&)*/
        virtual gzDynamicType onInvoke(const gzDistInvokeMessage& message) { GZ_DIST_ASSERT(FALSE); return 0.0; }

    private:
        gzVoid create();

        // This is the method the manager calls to add messages to client.
        gzVoid addClientMessage(gzDistNotification* notification);

        // Process the messages from sessions etc. Called by gzDistClientThread.
        gzBool processClientMessages();
        
        // Put a message in out queue.
        gzVoid addOutMessage(gzDistClientMessage* message, gzBool prio = FALSE);

        // Wait until operation is complete or timeout has elapsed,
        // if the message was an acknowledge message.
        gzBool waitAck(gzDistClientMessage* message, gzInt timeOut);

        // Switch list with client. Called by the manager when processing the client message.
        gzVoid switchList(gzDistClientMessageList** list);

        // Switch list with client.
        // Called by the gzDistClientThread when processing the received messages.
        gzUInt switchNotificationList();

        gzVoid onNotification(gzDistNotification* notification);

        gzVoid addToTransaction(gzDistNotificationData* data);

        //gzVoid setTransaction(gzRefList<gzDistNotificationData>* data);
        gzVoid setTransaction(gzDistNotificationSet* data);

        gzVoid endTransaction(const gzDistNotificationType type, gzDistObject* object);

        // Lock and return a pointer to m_managerProcessList. Null if no messages are available.
        gzDistClientMessageList* getManagerDataList();

        // Unlock m_managerProcessList.
        gzVoid dropManagerDataList();

        gzBool isBoosted();

        gzULong getThreadPoolId();

    // Members:

        // The global identification of the client.
        const gzDistClientID m_identification;


        // This pointer will point on the notification list, that is processed by the client thread.
        gzDistNotificationList* m_clientNotificationList;

        // This pointer will point on the list where all notifications to a client are placed.
        gzDistNotificationList* m_managerNotificationList;
        
        // This mutex is used when accessing m_clientNotificationListPtr
        gzMutex m_clientNotificationListMutex;

        // This mutex is used when accessing m_managerNotificationListPtr
        gzMutex m_managerNotificationListMutex;


        // This member will point on a list that the manager is processing.
        gzDistClientMessageList* m_managerProcessList;

        // This member will point on a list where all outgoing messages are put.
        gzDistClientMessageList* m_clientSendList;

        // This mutex is used to access m_managerProcessList
        gzMutex m_managerProcessListMutex;

        // This mutex is used to access m_sendQueue
        gzMutex m_clientSendListMutex;

        
        // The interval the client has desired to be "ticked" with.
        gzDouble m_clientTickInterval;

        // Next time the client will be "ticked".
        gzDouble m_nextTickTime;

        // Previous tick time. Used to calculate a more precise m_nextTickTime.
        gzDouble m_lastTickTime;

        // The thread pool id the client is using.
        gzULong m_threadPoolId;

        // Pointer to the thread this client is using.
        class gzDistThreadInterface* m_thread;

        // This member will temporary hold the transaction data during a transaction notification.
        //gzRefList<gzDistNotificationData>* m_transactionData;
        gzDistNotificationSet* m_transactionData;

        // Tells if missed "ticks" to onClientTick() shall be accumulated or skipped.
        gzBool m_skipTick;

        // Tells if the interface is initialized.
        gzBool m_initialized;

        gzBool m_responseBoost;

        // Flag to prevent recursive calls
        gzBool m_processing;
};


// Internal client message types
enum gzDistClientMessageType
{
    GZ_CLIENT_MESSAGE_TYPE_JOIN_SESSION = 1,
    GZ_CLIENT_MESSAGE_TYPE_RESIGN_SESSION,
    GZ_CLIENT_MESSAGE_TYPE_SEND_EVENT,
    GZ_CLIENT_MESSAGE_TYPE_ADD_OBJECT,
    GZ_CLIENT_MESSAGE_TYPE_REMOVE_OBJECT,
    GZ_CLIENT_MESSAGE_TYPE_SUBSCRIBE_OBJECT,
    GZ_CLIENT_MESSAGE_TYPE_UNSUBSCRIBE_OBJECT,
    GZ_CLIENT_MESSAGE_TYPE_SUBSCRIBE_EVENT,
    GZ_CLIENT_MESSAGE_TYPE_UNSUBSCRIBE_EVENT,
    GZ_CLIENT_MESSAGE_TYPE_SUBSCRIBE_NEW_ATTRIBUTES,
    GZ_CLIENT_MESSAGE_TYPE_UNSUBSCRIBE_NEW_ATTRIBUTES,
    GZ_CLIENT_MESSAGE_TYPE_SUBSCRIBE_ATTRIBUTE,         // Subscribe an attribute value
    GZ_CLIENT_MESSAGE_TYPE_UNSUBSCRIBE_ATTRIBUTE,       // Unsubscribe an attribute value
    GZ_CLIENT_MESSAGE_TYPE_SUBSCRIBE_SESSIONS,
    GZ_CLIENT_MESSAGE_TYPE_UNSUBSCRIBE_SESSIONS,
    GZ_CLIENT_MESSAGE_TYPE_GET_SESSION,
    GZ_CLIENT_MESSAGE_TYPE_GET_ADD_SESSION,
    GZ_CLIENT_MESSAGE_TYPE_REMOVE_SESSION,
    GZ_CLIENT_MESSAGE_TYPE_UPDATE_OBJECT,
    GZ_CLIENT_MESSAGE_TYPE_REMOVE_ATTRIBUTES,
    GZ_CLIENT_MESSAGE_TYPE_REQUEST_OWNERSHIP,
    GZ_CLIENT_MESSAGE_TYPE_DROP_OWNERSHIP,
    GZ_CLIENT_MESSAGE_TYPE_PULL_OWNERSHIP
};

GZ_DIST_DECLARE_MEMBASE(gzDistClientMessage);

// Internal client message
class gzDistClientMessage : public gzDistThreadSafeReference GZ_DIST_MEMBASE(gzDistClientMessage)
{
    public:
        GZ_DIST_MEMBASE_IMP(gzDistClientMessage);

        GZ_DIST_MEMBASE_CALL(gzDistClientMessage);

        // Constructor for join/resign session and remove object.
        gzDistClientMessage(const gzDistClientMessageType type, const gzDistSessionPtr& reference, gzBool ack);

        // Constructor for subscribe/unsubscribe object and event.
        gzDistClientMessage(const gzDistClientMessageType type, const gzDistSessionPtr& session, gzType* classType, gzBool ack, gzBool notifyExisting = FALSE);

        // Constructor for subscribe/unsubscribe an attribute in object.
        gzDistClientMessage(const gzDistClientMessageType type, const gzDistObjectPtr& object, const gzString& attributeName, gzBool ack, gzBool notifyExisting = FALSE);

        // Constructor for send/add event/object to session. Update object. Subscribe new attributes on object.
        gzDistClientMessage(const gzDistClientMessageType type, const gzDistThreadSafeReferencePtr& ref, const gzDistThreadSafeReferencePtr& addRef, gzBool ack, gzBool notifyExisting = FALSE);

        // Destructor
        virtual ~gzDistClientMessage();

        // Get session pointer.
        gzDistSession* getSession();

        // Get object pointer.
        gzDistObject* getObject();

        // Get event pointer.
        gzDistEvent* getEvent();

        // Get transaction pointer.
        gzDistTransaction* getTransaction();

        // Set transaction pointer.
        gzVoid getTransaction(gzDistTransaction* transaction);

        // The attribute in an attribute subscription.
        gzString* m_attributeName;

        // This member will contain the class type that should be subscribed/unsubscribed.
        gzType* m_classType;

        // Type of message
        gzDistClientMessageType m_messageType;

        // Tells if a subscription shall generate notification on existing data.
        gzBool m_notifyExisting;

        // This member is set to TRUE if a synchronous message is desired. The manager will zero this flag when operation is complete.
        gzBool m_acknowledge;

        // The distribution manager will put the result of the message here.
        gzBool m_result;

    private:

        // A reference to data that will be sent (object, event etc.)
        gzDistThreadSafeReferencePtr m_reference;

        // A reference a session or a transaction.
        gzDistThreadSafeReferencePtr m_additional_ref;

};


class gzDistInvokeMessage
{
    public:
        GZ_DIST_EXPORT gzDistInvokeMessage(){}
        GZ_DIST_EXPORT gzDistInvokeMessage(gzULong type, const gzDynamicType& data) : messageType(type), messageData(data) {}
        GZ_DIST_EXPORT gzDistInvokeMessage(gzULong type) : messageType(type) {}
        GZ_DIST_EXPORT ~gzDistInvokeMessage(){}

        gzULong messageType;
        gzDynamicType messageData;
};

#endif

---