stk-code_catmod/src/network/protocol_manager.hpp

//
//  SuperTuxKart - a fun racing game with go-kart
//  Copyright (C) 2013 SuperTuxKart-Team
//
//  This program is free software; you can redistribute it and/or
//  modify it under the terms of the GNU General Public License
//  as published by the Free Software Foundation; either version 3
//  of the License, or (at your option) any later version.
//
//  This program 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 General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

/*! \file protocol_manager.hpp
 *  \brief Contains structures and enumerations related to protocol management.
 */

#ifndef PROTOCOL_MANAGER_HPP
#define PROTOCOL_MANAGER_HPP

#include "network/singleton.hpp"
#include "network/event.hpp"

#include <vector>
#include <stdint.h>

class Protocol;

/*! 
 * \enum PROTOCOL_STATE
 * \brief Defines the three states that a protocol can have.
 */
enum PROTOCOL_STATE
{
    PROTOCOL_STATE_RUNNING,     //!< The protocol is being updated everytime.
    PROTOCOL_STATE_PAUSED,      //!< The protocol is paused. 
    PROTOCOL_STATE_TERMINATED   //!< The protocol is terminated/does not exist.
};

/*! 
 * \enum PROTOCOL_REQUEST_TYPE
 * \brief Defines actions that can be done about protocols.
 * This enum is used essentially to keep the manager thread-safe and 
 * to avoid protocols modifying directly their state.
 */
enum PROTOCOL_REQUEST_TYPE
{
    PROTOCOL_REQUEST_START,     //!< Start a protocol
    PROTOCOL_REQUEST_STOP,      //!< Stop a protocol 
    PROTOCOL_REQUEST_PAUSE,     //!< Pause a protocol
    PROTOCOL_REQUEST_UNPAUSE,   //!< Unpause a protocol
    PROTOCOL_REQUEST_TERMINATE  //!< Terminate a protocol
};

/*! 
* \struct ProtocolInfo
* \brief Stores the information needed to manage protocols
*/
typedef struct ProtocolInfo
{
    PROTOCOL_STATE  state;      //!< The state of the protocol
    Protocol*       protocol;   //!< A pointer to the protocol
    uint32_t        id;         //!< The unique id of the protocol
} ProtocolInfo;
    
/*!
* \struct ProtocolRequest
* \brief Represents a request to do an action about a protocol.
*/
typedef struct ProtocolRequest
{
    PROTOCOL_REQUEST_TYPE type; //!< The type of request
    ProtocolInfo protocol_info; //!< The concerned protocol information
} ProtocolRequest;

/*! 
 * \class ProtocolManager
 * \brief Manages the protocols at runtime.
 * 
 * This class is in charge of storing and managing protocols. 
 * It is a singleton as there can be only one protocol manager per game 
 * instance. Any game object that wants to start a protocol must create a 
 * protocol and give it to this singleton. The protocols are updated in a 
 * special thread, to ensure that they are processed independently from the
 * frames per second. Then, the management of protocols is thread-safe: any 
 * object can start/pause/stop protocols whithout problems.
 */
class ProtocolManager : public Singleton<ProtocolManager>
{
    friend class Singleton<ProtocolManager>;
    
    public:
        /*!
         * \brief Function that processes incoming events.
         * This function is called by the network manager each time there is an
         * incoming packet. 
         */
        virtual void            notifyEvent(Event* event);
        /*! 
         * \brief WILL BE COMMENTED LATER
         */
        virtual void            sendMessage(Protocol* sender, std::string message);
        
        /*! 
         * \brief Asks the manager to start a protocol.
         * This function will store the request, and process it at a time it is
         * thread-safe.
         * \param protocol : A pointer to the protocol to start
         * \return The unique id of the protocol that is being started.
         */
        virtual int             requestStart(Protocol* protocol);
        /*! 
         * \brief Asks the manager to stop a protocol.
         * This function will store the request, and process it at a time it is
         * thread-safe.
         * \param protocol : A pointer to the protocol to stop
         */
        virtual void            requestStop(Protocol* protocol);
        /*! 
         * \brief Asks the manager to pause a protocol.
         * This function will store the request, and process it at a time it is
         * thread-safe.
         * \param protocol : A pointer to the protocol to pause
         */
        virtual void            requestPause(Protocol* protocol);
        /*! 
         * \brief Asks the manager to unpause a protocol.
         * This function will store the request, and process it at a time it is
         * thread-safe.
         * \param protocol : A pointer to the protocol to unpause
         */
        virtual void            requestUnpause(Protocol* protocol);
        /*! 
         * \brief Notifies the manager that a protocol is terminated.
         * This function will store the request, and process it at a time it is
         * thread-safe.
         * \param protocol : A pointer to the protocol that is finished
         */
        virtual void            requestTerminate(Protocol* protocol);
         
        /*! 
         * \brief Updates the manager.
         * 
         * This function processes the events queue, notifies the concerned 
         * protocols that they have events to process. Then ask all protocols
         * to update themselves. Finally processes stored requests about 
         * starting, stoping, pausing etc... protocols.
         * This function is called by a thread as often as possible.
         * This function is not FPS-dependant.
         */
        virtual void            update();
        
        /*! 
         * \brief Get the number of protocols running.
         * \return The number of protocols that are actually running.
         */
        virtual int             runningProtocolsCount();
        /*!
         * \brief Get the state of a protocol using its id.
         * \param id : The id of the protocol you seek the state.
         * \return The state of the protocol. 
         */
        virtual PROTOCOL_STATE  getProtocolState(uint32_t id);
        /*!
         * \brief Get the state of a protocol using a pointer on it.
         * \param protocol : A pointer to the protocol you seek the state.
         * \return The state of the protocol. 
         */
        virtual PROTOCOL_STATE  getProtocolState(Protocol* protocol);
        /*!
         * \brief Get the id of a protocol.
         * \param protocol : A pointer to the protocol you seek the id.
         * \return The id of the protocol pointed by the protocol parameter.
         */
        virtual int             getProtocolID(Protocol* protocol);
        
    protected:
        // protected functions
        /*! 
         * \brief Constructor
         */
        ProtocolManager();
        /*! 
         * \brief Destructor
         */
        virtual ~ProtocolManager();
        /*!
         * \brief Assign an id to a protocol.
         * This function will assign m_next_protocol_id as the protocol id.
         * This id starts at 0 at the beginning and is increased by 1 each time
         * a protocol starts.
         * \param protocol_info : The protocol info that needs an id.
         */
        void                    assignProtocolId(ProtocolInfo* protocol_info);
        
        /*!
         * \brief Starts a protocol.
         * Add the protocol info to the m_protocols vector.
         * \param protocol : ProtocolInfo to start.
         */
        virtual void            startProtocol(ProtocolInfo protocol);
        /*!
         * \brief Stops a protocol.
         * Coes nothing. Noone can stop running protocols for now.
         * \param protocol : ProtocolInfo to stop.
         */
        virtual void            stopProtocol(ProtocolInfo protocol);
        /*!
         * \brief Pauses a protocol.
         * Pauses a protocol and tells it that it's being paused.
         * \param protocol : ProtocolInfo to pause.
         */
        virtual void            pauseProtocol(ProtocolInfo protocol);
        /*!
         * \brief Unpauses a protocol.
         * Unpauses a protocol and notifies it.
         * \param protocol : ProtocolInfo to unpause.
         */
        virtual void            unpauseProtocol(ProtocolInfo protocol);
        /*!
         * \brief Notes that a protocol is terminated.
         * Remove a protocol from the protocols vector.
         * \param protocol : ProtocolInfo concerned.
         */
        virtual void            protocolTerminated(ProtocolInfo protocol);
        
        // protected members
        /*! 
         * \brief Contains the running protocols.
         * This stores the protocols that are either running or paused, their 
         * state and their unique id.
         */
        std::vector<ProtocolInfo>       m_protocols;
        /*!
         * \brief Contains the network events to pass to protocols.
         */
        std::vector<Event*>             m_events_to_process;
        /*!
         * \brief Contains the requests to start/stop etc... protocols.
         */
        std::vector<ProtocolRequest>    m_requests;
        /*! \brief The next id to assign to a protocol. 
         * This value is incremented by 1 each time a protocol is started. 
         * If a protocol has an id lower than this value, it means that it have
         * been formerly started. 
         */
        unsigned int                    m_next_protocol_id;
        
        // mutexes:
        /*! Used to ensure that the event queue is used thread-safely.       */
        pthread_mutex_t                 m_events_mutex;
        /*! Used to ensure that the protocol vector is used thread-safely.   */
        pthread_mutex_t                 m_protocols_mutex;
        /*! Used to ensure that the request vector is used thread-safely.    */
        pthread_mutex_t                 m_requests_mutex;
        /*! Used to ensure that the protocol id is used in a thread-safe way.*/
        pthread_mutex_t                 m_id_mutex;
        
};

#endif // PROTOCOL_MANAGER_HPP