ExpansibleBandBlocksManager.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/memory/ExpansibleBandBlocksManager.h
22 
23  \brief RAM cached and tiled raster band blocks manager.
24 */
25 
26 #ifndef __TERRALIB_MEMORY_INTERNAL_EXPANSIBLEBANDBLOCKSMANAGER_H
27 #define __TERRALIB_MEMORY_INTERNAL_EXPANSIBLEBANDBLOCKSMANAGER_H
28 
29 // TerraLib
30 #include "../raster/Raster.h"
31 #include "Config.h"
32 
33 // STL
34 #include <cstdio>
35 #include <list>
36 #include <vector>
37 #include <string>
38 
39 // Boost
40 #include <boost/noncopyable.hpp>
41 #include <boost/shared_ptr.hpp>
42 #include <boost/shared_array.hpp>
43 
44 namespace te
45 {
46  namespace mem
47  {
48  /*!
49  \class ExpansibleBandBlocksManager
50 
51  \brief RAM cached and tiled raster band blocks manager.
52  */
53  class TEMEMORYEXPORT ExpansibleBandBlocksManager : private boost::noncopyable
54  {
55  public:
56 
57  /*!
58  \brief 3D Block index.
59  */
61  {
62  public :
63 
64  typedef unsigned int CoordDataType; //!< Coords data type.
65 
66  CoordDataType m_dim0Index; //!< Block Z (band) index.
67 
68  CoordDataType m_dim1Index; //!< Block Y index.
69 
70  CoordDataType m_dim2Index; //!< Block X index.
71 
72  BlockIndex3D() : m_dim0Index( 0 ), m_dim1Index( 0 ), m_dim2Index( 0 ) {};
73 
74  BlockIndex3D( const CoordDataType& dim0Index, const CoordDataType& dim1Index,
75  const CoordDataType& dim2Index ) : m_dim0Index( dim0Index ),
76  m_dim1Index( dim1Index ), m_dim2Index( dim2Index ) {};
77 
79  };
80 
82 
84 
85  /*!
86  \brief Initialize this instance to an initial state.
87 
88  \param maxNumberRAMBlocks The maximum number of RAM blocks.
89 
90  \param numbersOfBlocksX The number of blocks along the X directon (for each band).
91 
92  \param numbersOfBlocksY The number of blocks along the Y directon (for each band).
93 
94  \param blocksSizesBytes The blocks sizes in bytes (for each band).
95 
96  \param maxDiskFilesSize The maximum temporary disk file size (if required).
97 
98  \return true if OK, false on errors.
99  */
100  bool initialize( const unsigned int maxNumberRAMBlocks,
101  const std::vector< unsigned int>& numbersOfBlocksX,
102  const std::vector< unsigned int>& numbersOfBlocksY,
103  const std::vector< unsigned int>& blocksSizesBytes,
104  const unsigned long int maxDiskFilesSize );
105 
106  /*!
107  \brief Returns true if this instance is initialized.
108 
109  \return true if this instance is initialized.
110  */
111  bool isInitialized() const
112  {
113  return m_isInitialized;
114  };
115 
116  /*!
117  \brief Returns the number of blocks along the X directon for the required band.
118 
119  \param band The required band.
120 
121  \return Returns the number of blocks along the X directon for the required band.
122  */
123  unsigned int getNumberOfBlocksX( const unsigned int band ) const
124  {
125  assert( m_ramBlocksPointers.size() > band );
126  assert( m_ramBlocksPointers[ band ].size() > 0 );
127  return (unsigned int)m_ramBlocksPointers[ band ][ 0 ].size();
128  };
129 
130  /*!
131  \brief Returns the number of blocks along the Y directon for the required band.
132 
133  \param band The required band.
134 
135  \return Returns the number of blocks along the Y directon for the required band.
136  */
137  unsigned int getNumberOfBlocksY(
138  const unsigned int band ) const
139  {
140  assert( m_ramBlocksPointers.size() > band );
141  return (unsigned int)m_ramBlocksPointers[ band ].size();
142  };
143 
144  /*!
145  \brief Returns the number of bands.
146 
147  \return Returns the number of bands.
148  */
149  unsigned int getNumberOfBands() const
150  {
151  return (unsigned int)m_ramBlocksPointers.size();
152  };
153 
154  /*!
155  \brief Returns the internal size( bytes ) used for all internal blocks.
156 
157  \return Returns the internal size( bytes ) used for all internal blocks
158  */
159  unsigned long int getBlockSizeBytes()
160  {
161  return m_maxBlockSizeBytes;
162  };
163 
164  /*! \brief Free all allocated internal resources and go back to the initial state. */
165  void free();
166 
167  /*!
168  \brief Returns a pointer to the required data block.
169 
170  \param band The band index.
171  \param x The block-id in x (or x-offset).
172  \param y The block-id in y (or y-offset).
173 
174  \return Pointer to the required data block.
175  */
176  void* getBlockPointer(unsigned int band, unsigned int x, unsigned int y );
177 
178  /*! \brief The maximum number of cache blocks. */
179  unsigned int getMaxNumberOfRAMBlocks() const
180  {
181  return m_maxNumberRAMBlocks;
182  };
183 
184  /*!
185  \brief New blocks will be added at the top of the raster.
186 
187  \param expansionSize The expansion size over the Y direction.
188 
189  \param band The band where the operation will be performed.
190 
191  \param addedBlocksCoords The added blocks coords.
192 
193  \return true if OK, false on errors.
194  */
195  bool addTopBlocks( const unsigned int& expansionSize,
196  const unsigned int& band,
197  std::vector< BlockIndex3D >& addedBlocksCoords );
198 
199  /*!
200  \brief New blocks will be added at the bottom of the raster.
201 
202  \param expansionSize The expansion size over the Y direction.
203 
204  \param band The band where the operation will be performed.
205 
206  \param addedBlocksCoords The added blocks coords.
207 
208  \return true if OK, false on errors.
209  */
210  bool addBottomBlocks( const unsigned int& expansionSize,
211  const unsigned int& band,
212  std::vector< BlockIndex3D >& addedBlocksCoords );
213 
214  /*!
215  \brief New blocks will be added at the left of the raster.
216 
217  \param expansionSize The expansion size over the X direction.
218  \param band The band where the operation will be performed.
219  \param addedBlocksCoords The added blocks coords.
220 
221  \return true if OK, false on errors.
222  */
223  bool addLeftBlocks( const unsigned int& expansionSize,
224  const unsigned int& band,
225  std::vector< BlockIndex3D >& addedBlocksCoords );
226 
227  /*!
228  \brief New blocks will be added at the right of the raster.
229 
230  \param expansionSize The expansion size over the X direction.
231  \param band The band where the operation will be performed.
232  \param addedBlocksCoords The added blocks coords.
233 
234  \return true if OK, false on errors.
235  */
236  bool addRightBlocks( const unsigned int& expansionSize, const unsigned int& band,
237  std::vector< BlockIndex3D >& addedBlocksCoords );
238 
239  /*!
240  \brief New bands will be added at the top of the raster (before the first band).
241 
242  \param expansionSize The number of bands to add.
243 
244  \param addedBlocksCoords The added blocks coords.
245 
246  \return true if OK, false on errors.
247  */
248  bool addTopBands( const unsigned int& expansionSize,
249  std::vector< BlockIndex3D >& addedBlocksCoords );
250 
251  /*!
252  \brief New bands will be added at the bottom of the raster (after de the last band).
253 
254  \param expansionSize The number of bands to add.
255  \param addedBlocksCoords The added blocks coords.
256 
257  \return true if OK, false on errors.
258  */
259  bool addBottomBands( const unsigned int& expansionSize,
260  std::vector< BlockIndex3D >& addedBlocksCoords );
261 
262  protected :
263 
264  /*!
265  \brief Disk block info.
266  */
268  {
269  public :
270 
271  FILE* m_filePtr;
272  unsigned long int m_fileOff;
273 
274  DiskBlockInfo() : m_filePtr( 0 ), m_fileOff( 0 ) {};
275 
277  };
278 
279  /*!
280  \brief Open disk file handler.
281  */
282  class OpenDiskFileHandler : private boost::noncopyable
283  {
284  public :
285 
286  FILE* m_filePtr;
287 
288  std::string m_fullFileName;
289 
291 
293 
294  };
295 
296  typedef boost::shared_ptr< OpenDiskFileHandler > OpenDiskFileHandlerPtrT; //!< Open disk file pointer type.
297 
298  typedef std::list< OpenDiskFileHandlerPtrT > OpenDiskFilesHandlerT; //!< Open dis files handler type.
299 
300 
301  /*!
302  \brief Initialize this instance to an initial state.
303  */
304  void initState();
305 
306  /*!
307  \brief Allocate disk blocks.
308 
309  \param blocksNumber The number of blocks to allocate.
310 
311  \param diskBlocksInfos The info for the allocated blocks.
312 
313  \param diskFilesHandler The file handlers for all the allocated blocks.
314 
315  \return true if OK. false on errors.
316  */
317  bool allocateDiskBlocks( const unsigned int blocksNumber,
318  std::vector< DiskBlockInfo >& diskBlocksInfos,
319  OpenDiskFilesHandlerT& diskFilesHandler ) const;
320 
321  /*!
322  \brief Allocate and activate disk blocks.
323 
324  \param blocksIndxes The blocks indexes inside the internal 3D indexing matrices.
325 
326  \return true if OK. false on errors.
327  */
328  bool allocateAndActivateDiskBlocks( const std::vector< BlockIndex3D >& blocksIndxes );
329 
330  /*!
331  \brief Create a new disk file.
332 
333  \param size The file size.
334 
335  \param fileptr The file pointer.
336 
337  \param fullFileName The full created file name.
338 
339  \return true if OK. false on errors.
340  */
341  bool createNewDiskFile( unsigned long int size, FILE** fileptr,
342  std::string& fullFileName ) const;
343 
344  /*!
345  \brief Shift coords given a fixed dimention 0 index.
346 
347  \param inputContainer The input coords container.
348 
349  \param dim0index The dimension 0 fixed index.
350 
351  \param dim1Shift The shift to be done over the dimension 1.
352 
353  \param dim2Shift The shift to be done over the dimension 2.
354  */
355  template< typename ContainerType >
357  ContainerType& inputContainer,
358  const unsigned int dim0index, const int dim1Shift, const int dim2Shift ) const
359  {
360  typename ContainerType::iterator it = inputContainer.begin();
361  const typename ContainerType::iterator itE = inputContainer.end();
362  BlockIndex3D newCoords;
363 
364  while( it != itE )
365  {
366  if( it->m_dim0Index == dim0index )
367  {
368  assert( ( dim1Shift < 0 ) ? ( ((int)it->m_dim1Index) > dim1Shift ) : true );
369  it->m_dim1Index = (BlockIndex3D::CoordDataType)
370  ( ((int)it->m_dim1Index) + dim1Shift );
371 
372  assert( ( dim2Shift < 0 ) ? ( ((int)it->m_dim2Index) > dim2Shift ) : true );
373  it->m_dim2Index = (BlockIndex3D::CoordDataType)
374  ( ((int)it->m_dim2Index) + dim2Shift );
375  }
376 
377  ++it;
378  }
379  }
380 
381  /*!
382  \brief Shift 3D coords.
383 
384  \param inputContainer The input coords container.
385 
386  \param dim0Shift The shift to be done over the dimension 0.
387 
388  \param dim1Shift The shift to be done over the dimension 1.
389 
390  \param dim2Shift The shift to be done over the dimension 2.
391  */
392  template< typename ContainerType >
394  ContainerType& inputContainer,
395  const int& dim0Shift, const int& dim1Shift, const int& dim2Shift ) const
396  {
397  typename ContainerType::iterator it = inputContainer.begin();
398  const typename ContainerType::iterator itE = inputContainer.end();
399  BlockIndex3D newCoords;
400 
401  while( it != itE )
402  {
403  assert( ( dim0Shift < 0 ) ? ( ((int)it->m_dim0Index) > dim0Shift ) : true );
404  it->m_dim0Index = (BlockIndex3D::CoordDataType)
405  ( ((int)it->m_dim0Index) + dim0Shift );
406 
407  assert( ( dim1Shift < 0 ) ? ( ((int)it->m_dim1Index) > dim1Shift ) : true );
408  it->m_dim1Index = (BlockIndex3D::CoordDataType)
409  ( ((int)it->m_dim1Index) + dim1Shift );
410 
411  assert( ( dim2Shift < 0 ) ? ( ((int)it->m_dim2Index) > dim2Shift ) : true );
412  it->m_dim2Index = (BlockIndex3D::CoordDataType)
413  ( ((int)it->m_dim2Index) + dim2Shift );
414 
415  ++it;
416  }
417  }
418 
419  protected:
420 
421  typedef unsigned char BlockElementT; //!< Block element type.
422 
423  typedef BlockElementT* BlockelementPtrT; //!< Block element pointer type.
424 
425  typedef boost::shared_array< BlockElementT > RAMBlockHandlerT; //!< RAM Block handler type;
426 
427  typedef std::vector< std::vector< std::vector< BlockelementPtrT > > > RAMBlocksPointersContainerT; //!< RAM blocks pointers container type.
428 
429  typedef std::list< RAMBlockHandlerT > RAMBlocksHandlerT; //!< Blocks handler type;
430 
431  typedef std::vector< std::vector< std::vector< DiskBlockInfo > > > ActiveDiskBlocksInfoT; //!< Active disk blocks info type;
432 
433  typedef std::list< DiskBlockInfo > InactiveDiskBlocksInfoT; //!< Inactive disk blocks info type.
434 
435  typedef std::vector< BlockIndex3D > SwapFifoT; //!< Swap fifo type.
436 
437  bool m_isInitialized; //!< Is this instance initialized ?
438 
439  unsigned int m_maxNumberRAMBlocks; //!< The maximum number of RAM blocks;
440 
441  unsigned long int m_maxDiskFilesSize; //!< The maximum temporary disk file size (bytes).
442 
443  unsigned long int m_maxBlockSizeBytes; //!< The maximum global used block size in bytes.
444 
445  unsigned char* m_currSwapBlockPtr; //!< A pointer to the current block where disk data swap will be done.
446 
447  SwapFifoT::size_type m_nextFIFOPositionOverSwapFifo; //!< The next position where a block swap will occur over m_swapFifo;
448 
449  RAMBlocksHandlerT m_activeRAMBlocksHandler; //!< The active RAM blocks handler.
450 
451  RAMBlocksPointersContainerT m_ramBlocksPointers; //!< 3D Matrix of active RAM blocks pointers indexed in the form [band][blockYIndex][blockXIndex].
452 
453  SwapFifoT m_swapFifo; //!< Disk swapping FIFO.
454 
455  ActiveDiskBlocksInfoT m_activeDiskBlocksInfo; //!< 3D Matrix of active disk block info indexed as [band][blockYIndex][blockXIndex].
456 
457  OpenDiskFilesHandlerT m_diskFilesHandler; //!< The disk files handler;
458 
459  RAMBlockHandlerT m_swapBlockHandler; //!< An extra block for disk swap purposes.
460 
461  private:
462 
463  // Variables used by the method getBlockPointer
465  };
466 
467  } // end namespace mem
468 } // end namespace te
469 
470 #endif // __TERRALIB_MEMORY_INTERNAL_EXPANSIBLEBANDBLOCKSMANAGER_H
unsigned char * m_currSwapBlockPtr
A pointer to the current block where disk data swap will be done.
RAMBlocksPointersContainerT m_ramBlocksPointers
3D Matrix of active RAM blocks pointers indexed in the form [band][blockYIndex][blockXIndex].
#define TEMEMORYEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:84
void shift3DCoords(ContainerType &inputContainer, const int &dim0Shift, const int &dim1Shift, const int &dim2Shift) const
Shift 3D coords.
std::list< OpenDiskFileHandlerPtrT > OpenDiskFilesHandlerT
Open dis files handler type.
std::vector< std::vector< std::vector< DiskBlockInfo > > > ActiveDiskBlocksInfoT
Active disk blocks info type;.
std::vector< std::vector< std::vector< BlockelementPtrT > > > RAMBlocksPointersContainerT
RAM blocks pointers container type.
BlockIndex3D(const CoordDataType &dim0Index, const CoordDataType &dim1Index, const CoordDataType &dim2Index)
std::vector< BlockIndex3D > SwapFifoT
Swap fifo type.
unsigned int getNumberOfBands() const
Returns the number of bands.
Configuration flags for the TerraLib In-memory Data Access driver.
ActiveDiskBlocksInfoT m_activeDiskBlocksInfo
3D Matrix of active disk block info indexed as [band][blockYIndex][blockXIndex].
std::list< DiskBlockInfo > InactiveDiskBlocksInfoT
Inactive disk blocks info type.
unsigned long int m_maxBlockSizeBytes
The maximum global used block size in bytes.
RAMBlocksHandlerT m_activeRAMBlocksHandler
The active RAM blocks handler.
void shiftDim03DCoords(ContainerType &inputContainer, const unsigned int dim0index, const int dim1Shift, const int dim2Shift) const
Shift coords given a fixed dimention 0 index.
RAM cached and tiled raster band blocks manager.
URI C++ Library.
unsigned int getNumberOfBlocksY(const unsigned int band) const
Returns the number of blocks along the Y directon for the required band.
unsigned long int m_maxDiskFilesSize
The maximum temporary disk file size (bytes).
unsigned long int getBlockSizeBytes()
Returns the internal size( bytes ) used for all internal blocks.
bool isInitialized() const
Returns true if this instance is initialized.
SwapFifoT::size_type m_nextFIFOPositionOverSwapFifo
The next position where a block swap will occur over m_swapFifo;.
BlockElementT * BlockelementPtrT
Block element pointer type.
boost::shared_ptr< OpenDiskFileHandler > OpenDiskFileHandlerPtrT
Open disk file pointer type.
unsigned int getNumberOfBlocksX(const unsigned int band) const
Returns the number of blocks along the X directon for the required band.
boost::shared_array< BlockElementT > RAMBlockHandlerT
RAM Block handler type;.
bool m_isInitialized
Is this instance initialized ?
OpenDiskFilesHandlerT m_diskFilesHandler
The disk files handler;.
unsigned int m_maxNumberRAMBlocks
The maximum number of RAM blocks;.
unsigned int getMaxNumberOfRAMBlocks() const
The maximum number of cache blocks.
std::list< RAMBlockHandlerT > RAMBlocksHandlerT
Blocks handler type;.
unsigned char BlockElementT
Block element type.
RAMBlockHandlerT m_swapBlockHandler
An extra block for disk swap purposes.