CachedBandBlocksManager.h

Go to the documentation of this file.

/*  Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
 
    This file is part of the TerraLib - a Framework for building GIS enabled applications.
 
    TerraLib 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 3 of the License,
    or (at your option) any later version.
 
    TerraLib 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 TerraLib. See COPYING. If not, write to
    TerraLib Team at <terralib-team@terralib.org>.
 */
 
/*!
  \file terralib/memory/CachedBandBlocksManager.h
 
  \brief RAM cached and tiled raster band blocks manager.
*/
 
#ifndef __TERRALIB_MEMORY_INTERNAL_CACHEDBANDBLOCKSMANAGER_H
#define __TERRALIB_MEMORY_INTERNAL_CACHEDBANDBLOCKSMANAGER_H
 
// TerraLib
#include "../raster/Raster.h"
#include "Config.h"
 
// STL
#include <memory>
#include <vector>
 
// Boost
#include <boost/noncopyable.hpp>
#include <boost/thread.hpp>
#include <boost/scoped_array.hpp>
 
namespace te
{
  namespace mem
  {
    /*!
      \class CachedBandBlocksManager
 
      \brief RAM cached and tiled raster band blocks manager.
    */
    class TEMEMORYEXPORT CachedBandBlocksManager : public boost::noncopyable
    {
      public:
 
        CachedBandBlocksManager();
 
        ~CachedBandBlocksManager();
 
        /*!
          \brief Initialize this instance to an initial state.
 
          \param externalRaster The external raster where the data will be read/written.
 
          \param maxMemPercentUsed The maximum free memory percentual to use valid range: [1:100].
 
          \param dataPrefetchThreshold The read-ahead data prefetch threshold (0-will disable prefetch, 1-data always prefetched, higher values will do prefetch when necessary).
 
          \return true if OK, false on errors.
        */
        bool initialize( const te::rst::Raster& externalRaster,
                          const unsigned char maxMemPercentUsed,
                          const unsigned int dataPrefetchThreshold );
 
        /*!
          \brief Initialize this instance to an initial state.
 
          \param externalRaster The external raster where the data will be read/written.
 
          \param maxNumberOfCacheBlocks The maximum number of cache blocks.
 
          \param dataPrefetchThreshold The read-ahead data prefetch threshold (0-will disable prefetch, 1-data always prefetched, higher values will do prefetch when necessary).
 
          \return true if OK, false on errors.
        */
        bool initialize( const unsigned int maxNumberOfCacheBlocks, 
                          const te::rst::Raster& externalRaster, 
                          const unsigned int dataPrefetchThreshold );
 
        /*!
          \brief Returns true if this instance is initialized.
 
          \return true if this instance is initialized.
        */
        bool isInitialized() const
        {
          return m_rasterPtr ? true : false;
        };
 
        /*!
          \note Free all allocated internal resources and go back to the initial state.
        */
        void free(); 
 
        /*!
          \brief Returns a pointer to the required data block.
 
          \param band The band index.
          \param x    The block-id in x (or x-offset).
          \param y    The block-id in y (or y-offset).
 
          \return Pointer to the required data block.
        */
        void* getBlockPointer(unsigned int band, unsigned int x, unsigned int y );
 
 
        /*! \brief Returns the associated raster. */
        te::rst::Raster* getRaster() const
        {
          return m_rasterPtr;
        };
 
        /*! \brief The maximum number of cache blocks. */
        unsigned int getMaxNumberOfCacheBlocks() const
        {
          return m_maxNumberOfCacheBlocks;
        };
        
        /*! \brief The read-ahead data prefetch threshold. */
        unsigned int getDataPrefetchThreshold() const
        {
          return m_dataPrefetchThreshold;
        };
 
      protected :
 
        /*!
          \class BlockIndex
 
          \brief Internal blocks indexes.
        */
        class BlockIndex
        {
          public :
 
            unsigned int m_b; //!< Block band index
            unsigned int m_y; //!< Block index over the Y axis.
            unsigned int m_x; //!< Block index over the X axis.
 
            BlockIndex()
              : m_b( 0 ), m_y( 0 ), m_x( 0 )
            {
            }
 
            ~BlockIndex()
            {
            }
        };
 
        /*!
          \class ThreadParameters
 
          \brief Internal read/write thread execution parameters.
        */
        class ThreadParameters
        {
          public :
            
            enum TaskType
            {
              InvalidTaskT = 0,
              ReadTaskT = 1,      //!< m_exchangeBlockPtr must point to a valid exchange block (it will be keept inside the thread for further use), m_blockPtr must be zero and will be updated to point to the read block.
              WriteTaskT = 2,     //!< m_blockPtr must point to the block to be written, m_exchangeBlockPtr must be zero.
              SuicideTastT = 3    //!< The thread will finish the main loop and exit.
            };
 
            te::rst::Raster* m_rasterPtr; //!< External raster pointer.
 
            unsigned int m_dataPrefetchThreshold; //!< The user defined read-ahead threshold.
 
            bool m_taskFinished; //!< true when the thread has finished the required task.
 
            TaskType m_task; //!< The required task to be performed (read/write/exit).
 
            unsigned char* m_blockPtr; //!< Input block pointer.
 
            unsigned char* m_exchangeBlockPtr; //!< Exchange block pointer.
 
            unsigned int m_blockB; //!< Raster block band index.
 
            unsigned int m_blockX; //!< Raster block X index
 
            unsigned int m_blockY; //!< Raster block Y index
 
            boost::mutex m_doTaskMutex; //!< Used when wakenning the thread to perform some task.
 
            boost::mutex m_taskFinishedMutex; //!< used by the thread to inform a task finishment.
 
            boost::condition_variable m_doTaskCondVar; //!< Used by the thread when awakenning to perform some task.
 
            boost::condition_variable m_taskFinishedCondVar; //!< Used to wait for the required task finishment.
 
            boost::scoped_array< unsigned char > m_threadDataBlockHandler; //!< A extra block used in exchange when a read-ahead task is performed.
 
            ThreadParameters()
              : m_rasterPtr( 0 ),
                m_dataPrefetchThreshold( 0 ),
                m_taskFinished( false ),
                m_task( InvalidTaskT ), 
                m_blockPtr( 0 ),
                m_exchangeBlockPtr( 0 ),
                m_blockB( 0 ),
                m_blockX( 0 ),
                m_blockY( 0 )
            {
            };
 
            ~ThreadParameters() {};
        };
 
        te::rst::Raster* m_rasterPtr; //!< External raster pointer.
 
        unsigned int m_dataPrefetchThreshold; //!< The read-ahead data prefetch threshold (0-will disable prefetch, 1-data always prefetched, higher values will do prefetch when necessary).
 
        unsigned int m_globalBlocksNumberX; //!< The maximum number of blocks (X axis) for all bands.
 
        unsigned int m_globalBlocksNumberY; //!< The maximum number of blocks (Y axis) for all bands.
 
        unsigned int m_globalBlockSizeBytes; //!< The maximum block size for all bands.
 
        unsigned int m_maxNumberOfCacheBlocks; //!< The maximum number of cache blocks.
 
        unsigned int m_blocksFifoNextSwapBlockIndex; //!< The next block swapp index over m_blocksFifo.
 
// variables used by internal methods
        unsigned char* m_getBlockPointer_BlkPtr;
 
        std::vector< std::vector< std::vector< unsigned char* > > > m_blocksPointers; //!< 3D Matrix of block pointers indexed as [band][blockYIndex][blockXIndex].
 
        std::vector< unsigned char* > m_blocksHandler; //!< Cache blocks handler.
 
        std::vector< BlockIndex > m_blocksFifo; //!< blocks swap FIFO.
 
        ThreadParameters m_threadParams; //!< The internal thread execution parameters.
 
        std::unique_ptr< boost::thread > m_threadHandler; //!< The internal thread handler.
 
        /*! 
          \brief Thread entry.
 
          \param paramsPtr A pointer to the thread parameters.
        */
        static void threadEntry(ThreadParameters* paramsPtr);
 
      private :
 
        /*! \brief Initialize this instance to an initial state. */
        void initState();
    };
 
  } // end namespace mem
}   // end namespace te
 
#endif  // __TERRALIB_MEMORY_INTERNAL_CACHEDBANDBLOCKSMANAGER_H