SynchronizedBandBlocksManager.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18  */
19 
20 /*!
21  \file terralib/raster/SynchronizedBandBlocksManager.h
22 
23  \brief Synchronized raster raster band blocks manager.
24 */
25 
26 #ifndef __TERRALIB_RASTER_INTERNAL_SYNCHRONIZEDBANDBLOCKSMANAGER_H
27 #define __TERRALIB_RASTER_INTERNAL_SYNCHRONIZEDBANDBLOCKSMANAGER_H
28 
29 // TerraLib
30 #include "RasterSynchronizer.h"
31 #include "Config.h"
32 #include "../raster/Raster.h"
33 
34 // STL
35 #include <memory>
36 #include <vector>
37 
38 // Boost
39 #include <boost/noncopyable.hpp>
40 
41 namespace te
42 {
43  namespace rst
44  {
45  /*!
46  \class SynchronizedBandBlocksManager
47 
48  \brief Synchronized raster raster band blocks manager.
49  */
50  class TERASTEREXPORT SynchronizedBandBlocksManager : public boost::noncopyable
51  {
52  public:
53 
55 
57 
58  /*!
59  \brief Initialize this instance to an initial state.
60 
61  \param sync The synchronized used by this instance.
62 
63  \param maxMemPercentUsed The maximum free memory percentual to use valid range: [1:100].
64 
65  \return true if OK, false on errors.
66 
67  \note For the case where using the write raster access policy: The use of multiple cached blocks can cause deadlocks if multiple threads are locking blocks needed by other threads, use it with caution!
68  */
69  bool initialize( RasterSynchronizer& sync,
70  const unsigned char maxMemPercentUsed );
71 
72  /*!
73  \brief Initialize this instance to an initial state.
74 
75  \param sync The synchronized used by this instance.
76 
77  \param maxNumberOfCacheBlocks The maximum number of cache blocks.
78 
79  \return true if OK, false on errors.
80 
81  \note For the case where using the write raster access policy: The use of multiple cached blocks can cause deadlocks if multiple threads are locking blocks needed by other threads, use it with caution!
82  */
83  bool initialize( const unsigned int maxNumberOfCacheBlocks,
84  RasterSynchronizer& sync );
85 
86  /*!
87  \brief Returns true if this instance is initialized.
88 
89  \return true if this instance is initialized.
90  */
91  bool isInitialized() const
92  {
93  return m_syncPtr ? true : false;
94  };
95 
96  /*!
97  \note Free all allocated internal resources and go back to the initial state.
98  */
99  void free();
100 
101  /*!
102  \brief Returns a pointer to the required data block.
103 
104  \param band The band index.
105  \param x The block-id in x (or x-offset).
106  \param y The block-id in y (or y-offset).
107 
108  \return Pointer to the required data block.
109  */
110  void* getBlockPointer(unsigned int band, unsigned int x, unsigned int y );
111 
112 
113  /*! \brief Returns the associated raster. */
114  te::rst::Raster* getRaster() const;
115 
116  /*! \brief The maximum number of cache blocks. */
117  unsigned int getMaxNumberOfCacheBlocks() const
118  {
119  return m_maxNumberOfCacheBlocks;
120  };
121 
122  /*! \brief Return a pointer to the assotiated synchronizer instance or NULL if there is none. */
124  {
125  return m_syncPtr;
126  };
127 
128  protected :
129 
130  /*!
131  \class BlockIndex
132 
133  \brief Internal blocks indexes.
134  */
136  {
137  public :
138 
139  unsigned int m_b; //!< Block band index
140  unsigned int m_y; //!< Block index over the Y axis.
141  unsigned int m_x; //!< Block index over the X axis.
142 
144  : m_b( 0 ), m_y( 0 ), m_x( 0 )
145  {
146  }
147 
149  {
150  }
151  };
152 
153  RasterSynchronizer* m_syncPtr; //!< A pointer to the synchronizer used by this instance, of null if not initialized.
154 
155  unsigned int m_globalBlocksNumberX; //!< The maximum number of blocks (X axis) for all bands.
156 
157  unsigned int m_globalBlocksNumberY; //!< The maximum number of blocks (Y axis) for all bands.
158 
159  unsigned int m_globalBlockSizeBytes; //!< The maximum block size for all bands.
160 
161  unsigned int m_maxNumberOfCacheBlocks; //!< The maximum number of cache blocks.
162 
163  unsigned int m_blocksFifoNextSwapBlockIndex; //!< The next block swapp index over m_blocksFifo.
164 
165  // variables used by internal methods
166  unsigned char* m_getBlockPointer_BlkPtr;
167 
168  std::vector< std::vector< std::vector< unsigned char* > > > m_blocksPointers; //!< 3D Matrix of block pointers indexed as [band][blockYIndex][blockXIndex].
169 
170  std::vector< unsigned char* > m_blocksHandler; //!< Cache blocks handler.
171 
172  std::vector< BlockIndex > m_blocksFifo; //!< blocks swap FIFO.
173 
174  private :
175 
176  /*! \brief Initialize this instance to an initial state. */
177  void initState();
178  };
179 
180  } // end namespace mem
181 } // end namespace te
182 
183 #endif // __TERRALIB_RASTER_INTERNAL_SYNCHRONIZEDBANDBLOCKSMANAGER_H
#define TERASTEREXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:62
std::vector< std::vector< std::vector< unsigned char * > > > m_blocksPointers
3D Matrix of block pointers indexed as [band][blockYIndex][blockXIndex].
RasterSynchronizer * m_syncPtr
A pointer to the synchronizer used by this instance, of null if not initialized.
An access synchronizer to be used in SynchronizedRaster raster instances.
unsigned int m_blocksFifoNextSwapBlockIndex
The next block swapp index over m_blocksFifo.
std::vector< BlockIndex > m_blocksFifo
blocks swap FIFO.
std::vector< unsigned char * > m_blocksHandler
Cache blocks handler.
unsigned int m_maxNumberOfCacheBlocks
The maximum number of cache blocks.
unsigned int getMaxNumberOfCacheBlocks() const
The maximum number of cache blocks.
An abstract class for raster data strucutures.
Definition: Raster.h:71
URI C++ Library.
An access synchronizer to be used in SynchronizedRaster raster instances.
Synchronized raster raster band blocks manager.
bool isInitialized() const
Returns true if this instance is initialized.
unsigned int m_globalBlockSizeBytes
The maximum block size for all bands.
RasterSynchronizer * getSynchronizer() const
Return a pointer to the assotiated synchronizer instance or NULL if there is none.
Configuration flags for the Raster module of TerraLib.
unsigned int m_globalBlocksNumberY
The maximum number of blocks (Y axis) for all bands.
unsigned int m_globalBlocksNumberX
The maximum number of blocks (X axis) for all bands.