Beesnest/DcAdaptersSet.h

Go to the documentation of this file.

/*
Copyright 2007 Erez Bibi (erezbibi@users.sourceforge.net)
This file is part of Beesnest.

Beesnest 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 2 of the License, or
(at your option) any later version.

Beesnest 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 Beesnest; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

/* DcAdaptersSet.h: interface for the CdcAdaptersSet class. */

#ifndef __CDC_ADAPTERS_LIST
#define __CDC_ADAPTERS_LIST


#include "DcGlobals.h"
#include "DcHttpTime.h"
#include "DcAdaptersBank.h"
#include "Interfaces/DcAdapter.h"
#include "Interfaces/DcAdaptersSet.h"
#include _GET_INCLUDE_PATH (DcMutex.h)
#include _GET_INCLUDE_PATH (DcThread.h)

/**
 * This class implements the IdcAdaptersSet interface, it stores all the
 * adapters that in use by one user. It works closely with the CdcAdaptersBank
 * that allocates these adapters. However this class is the one that destroys
 * the adapters. When an engine needs to work with an adapter, it gets it's ID
 * from this class, and call Read and/or Write with this ID. When the engine is
 * done it either releases the adapters or calls Done on the adapters IDs.
 *
 * <p>
 * As Adapter Set works just with the scripting engines, it does not use
 * CdcString. Scripting engines does not know CdcString. It uses STL string.
 *
 * <p>
 * This class is thread safe, as user can have more then one thread going in
 * the same time. An adapter however, can be in use of just one thread at a time.
 *
 * <p>
 * @author Erez Bibi
 * @version 2.0
 */


class CdcAdaptersSet : public IdcAdaptersSet
{
private:

    /**
     * Class for one node in the adapters list.
     */
    class CdcAdapterNode
    {
    public:
        IdcAdapter* pAdapter;   /** Pointer to the adapter itself. */
        CdcHttpTime tStartIdle; /** Time of saving an adapter (idle start time) */
        int nValidSeconds;      /** Number of seconds to keep the adapter idle. */
        bool isFree;            /** Is adapter free flag */
        bool isMultiEngine;     /** True if this is a multi-use adapter. */
        bool isStorable;        /** True if need to save this adapter. */
        CdcString sName;        /** The adapter name. */
        uint nAID;              /** The adapter ID. */
    };

    typedef map <uint, CdcAdapterNode*> t_adapters_map;

    /** Map of adapters and IDs. */
    t_adapters_map mAdapters;

    /** Mutex for this object. */
    CdcMutex oMutex;

    /** True when this set is in a logged in state. */
    bool isLoggedIn;

    /** The "auto release" thread object. */
    CdcThread oReleaseThread;

    /** Flag to signal to the Release thread to exit
    (dynamically allocated by the class and delete by the limit thread).
    It works this way so the thread will still have something to look at
    even when the class object is deallocated. */
    volatile bool* isReleseThreadGo;

    /** Dynamically allocated Mutex to prevent Release Thread clash with other
    threads. */
    CdcMutex* poLimitMutex;

public:

    /**
     * Constructor - Does nothing.
     */
     CdcAdaptersSet ()
     :isReleseThreadGo (NULL), poLimitMutex (NULL), isLoggedIn (false){}

    /**
     * Destructor - Does nothing.
     */
     virtual ~CdcAdaptersSet() {}

    /**
     * Start the Release thread.
     */
    void Login ();

    /**
     * release all unused adapters, and close the Release thread.
     */
    void Logout ();

    /**
     * This function tries to find an (ID of) adapter by the name 'name'.
     * It looks first in the class adapters map. If it finds an adapter with
     * the same name that is free, it returns it's ID, and marks it as not free.
     * This adapter will always be a non multi-engine adapter, otherwise it
     * will not be saved as free adapter. If it finds a taken adapter in the map
     * and the adapter is non multi-engine, it returns 0. If it doesn't find an
     * adapter in the map, or it finds a taken one but it is a multi-engine
     * adapter, it tries to get the adapter from the Adapters Bank. The adapters
     * bank might return a new adapter or not.
     * <p>
     * @param name The desired adapter name.
     * @return (uint) The adapter ID or 0 if cannot get this adapter.
     */
    virtual uint GetAdapter (BufferHolder name);

    /** This function releases (delete) an adapter. The function notify the
     * Adapters Bank that it deletes this adapter. This notification is relevant
     * for the Bank, just if it marked this adapter as taken.
     * <p>
     * @param AID The adapter ID.
     * @param check_free Is a flag to indicate to this function not to
     * release the adapter if it is taken by another thread.
     */
    virtual void ReleaseAdapter (uint AID, bool check_free=false);

    /**
     * When an engine exits (done with a script) it calls this function on every
     * adapter it has (got with GetAdapter and didn't release). If the
     * adapter is not "Storable", the class will release (delete) it. If the
     * adapter is "Storable", the class will mark it as free, set the tStartIdle
     * time (for the release idles thread), but keep the adapter in its
     * adapters map.
     * <p>
     * @param AID The ID of the adapter an engine is done with.
     */
    void AdapterDone (uint AID);

    /**
     * This is the function that calls the adapter Read function. This function
     * does not lock the class Mutex.
     * <p>
     * @param AID The adapter ID.
     * @param address The address (or name) to read from.
     * @throw (BufferHolder) Just pass an exception from the adapter.
     * @return (BufferHolder) Holds the result string (or an empty string).
     */
    virtual BufferHolder Read (unsigned int AID, BufferHolder address)
        throw (BufferHolder);

    /**
     * This is the function that calls the adapter Write function. This function
     * does not lock the class Mutex.
     * <p>
     * @param AID The adapter ID.
     * @param address The address (or name) to write to.
     * @param value The string to write to this address (Optional).
     * @throw (BufferHolder) Just pass an exception from the adapter.
     * @return (bool) True on success.
     */
    virtual bool Write (uint AID, BufferHolder address, BufferHolder value)
        throw (BufferHolder);


    /**
     * This is a global friend function. This function runs as a
     * separate thread, has access to all the private members of the
     * class and in charge of releasing adapters that have not been
     * used for sometime. The time is defined in the parameters file
     * for each adapter. Adapter does not has to have a release time.
     */
    friend int DcRelease (void* pParam);
};

#endif /* __CDC_ADAPTERS_LIST */