# GDALRasterBlock Class Reference

A single raster block in the block cache. More...

`#include <gdal_priv.h>`

List of all members.

## Public Member Functions
| GDALRasterBlock (GDALRasterBand *, int, int)
| GDALRasterBlock Constructor.
virtual | ~GDALRasterBlock ()
| Block destructor.
CPLErr | Internalize (void)
| Allocate memory for block.
void | Touch (void)
| Push block to top of LRU (least-recently used) list.
void | MarkDirty (void)
| Mark the block as modified.
void | MarkClean (void)
| Mark the block as unmodified.
void | AddLock (void)
void | DropLock (void)
void | Detach ()
| Remove block from cache.
CPLErr | Write ()
| Force writing of the current block, if dirty.
GDALDataType | GetDataType ()
int | GetXOff ()
int | GetYOff ()
int | GetXSize ()
int | GetYSize ()
int | GetDirty ()
int | GetLockCount ()
void * | GetDataRef (void)
GDALRasterBand * | GetBand ()
| Accessor to source GDALRasterBand object.
## Static Public Member Functions
static int | FlushCacheBlock ()
| Attempt to flush at least one block from the cache.
static void | Verify ()
| Confirms (via assertions) that the block cache linked list is in a consistent state.
static int | SafeLockBlock (GDALRasterBlock **)
| Safely lock block.

## Detailed Description

A single raster block in the block cache.

GDALRasterBlock objects hold one block of raster data for one band that is currently stored in the GDAL raster cache.

The cache holds some blocks of raster data for zero or more GDALRasterBand objects across zero or more GDALDataset objects in a global raster cache with a least recently used (LRU) list and an upper cache limit (see GDALSetCacheMax()) under which the cache size is normally kept.

Some blocks in the cache may be modified relative to the state on disk (they are marked "Dirty") and must be flushed to disk before they can be discarded. Other (Clean) blocks may just be discarded if their memory needs to be recovered.

In normal situations applications do not interact directly with the GDALRasterBlock - instead it it utilized by the RasterIO() interfaces to implement caching.

Some driver classes are implemented in a fashion that completely avoids use of the GDAL raster cache (and GDALRasterBlock) though this is not very common.

## Constructor & Destructor Documentation

GDALRasterBlock::GDALRasterBlock | ( | GDALRasterBand * | poBandIn,
|  | int | nXOffIn,
|  | int | nYOffIn |
| ) |  |  |

GDALRasterBlock Constructor.

Normally only called from GDALRasterBand::GetLockedBlockRef().

Parameters:

  | poBandIn | the raster band used as source of raster block being constructed.
  | nXOffIn | the horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.
  | nYOffIn | the vertical block offset, with zero indicating the top most block, 1 the next block and so forth.

References GDALRasterBand::GetBlockSize(), and GDALRasterBand::GetRasterDataType().

GDALRasterBlock::~GDALRasterBlock | ( |  | ) | `[virtual]`

Block destructor.

Normally called from GDALRasterBand::FlushBlock().

References Detach(), GDALGetDataTypeSize(), and Verify().

## Member Function Documentation

CPLErr GDALRasterBlock::Internalize | ( | void |  | ) |

Allocate memory for block.

This method allocates memory for the block, and attempts to flush other blocks, if necessary, to bring the total cache size back within the limits. The newly allocated block is touched and will be considered most recently used in the LRU list.

Returns:
  CE_None on success or CE_Failure if memory allocation fails.

References GDALFlushCacheBlock(), GDALGetCacheMax64(), GDALGetDataTypeSize(), and Touch().

Referenced by GDALRasterBand::GetLockedBlockRef().

void GDALRasterBlock::Touch | ( | void |  | ) |

Push block to top of LRU (least-recently used) list.

This method is normally called when a block is used to keep track that it has been recently used.

References poNext, poPrevious, and Verify().

Referenced by Internalize().

void GDALRasterBlock::MarkDirty | ( | void |  | ) |

Mark the block as modified.

A dirty block is one that has been modified and will need to be written to disk before it can be flushed.

Referenced by GDALRasterBand::Fill().

void GDALRasterBlock::MarkClean | ( | void |  | ) |

Mark the block as unmodified.

A dirty block is one that has been modified and will need to be written to disk before it can be flushed.

Referenced by Write().

void GDALRasterBlock::Detach | ( |  | ) |

Remove block from cache.

This method removes the current block from the linked list used to keep track of all cached blocks in order of age. It does not affect whether the block is referenced by a GDALRasterBand nor does it destroy or flush the block.

References poNext, and poPrevious.

Referenced by FlushCacheBlock(), and ~GDALRasterBlock().

CPLErr GDALRasterBlock::Write | ( |  | ) |

Force writing of the current block, if dirty.

The block is written using GDALRasterBand::IWriteBlock() on it's corresponding band object. Even if the write fails the block will be marked clean.

Returns:
  CE_None otherwise the error returned by IWriteBlock().

References GDALRasterBand::eFlushBlockErr, GDALRasterBand::IWriteBlock(), and MarkClean().

GDALRasterBand* GDALRasterBlock::GetBand | ( |  | ) | `[inline]`

Accessor to source GDALRasterBand object.

Returns:
  source raster band of the raster block.

Referenced by FlushCacheBlock().

int GDALRasterBlock::FlushCacheBlock | ( |  | ) | `[static]`

Attempt to flush at least one block from the cache.

This static method is normally used to recover memory when a request for a new cache block would put cache memory use over the established limit.

C++ analog to the C function GDALFlushCacheBlock().

Returns:
  TRUE if successful or FALSE if no flushable block is found.

References Detach(), GDALRasterBand::FlushBlock(), GetBand(), GetLockCount(), GetXOff(), GetYOff(), poPrevious, and GDALRasterBand::SetFlushBlockErr().

Referenced by GDALFlushCacheBlock().

int GDALRasterBlock::SafeLockBlock | ( | GDALRasterBlock ** | ppBlock | ) | `[static]`

Safely lock block.

This method locks a GDALRasterBlock (and touches it) in a thread-safe manner. The global block cache mutex is held while locking the block, in order to avoid race conditions with other threads that might be trying to expire the block at the same time. The block pointer may be safely NULL, in which case this method does nothing.

Parameters:

  | ppBlock | Pointer to the block pointer to try and lock/touch.

Referenced by GDALRasterBand::TryGetLockedBlockRef().

The documentation for this class was generated from the following files:

- gdal_priv.h
- gdalrasterblock.cpp

Generated for GDAL by 1.5.6.