GDAL
Public Member Functions | Static Public Member Functions | Friends | List of all members
GDALRasterBlock Class Reference

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

#include <gdal_priv.h>

Public Member Functions

 GDALRasterBlock (GDALRasterBand *, int, int)
 GDALRasterBlock Constructor.
 
 GDALRasterBlock (int nXOffIn, int nYOffIn)
 GDALRasterBlock Constructor (for GDALHashSetBandBlockAccess purpose)
 
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.
 
int AddLock (void)
 Increment the lock count.
 
int DropLock (void)
 Decrement the lock count.
 
void Detach ()
 Remove block from cache.
 
CPLErr Write ()
 Force writing of the current block, if dirty.
 
GDALDataType GetDataType () const
 Return the data type.
 
int GetXOff () const
 Return the x offset of the top-left corner of the block.
 
int GetYOff () const
 Return the y offset of the top-left corner of the block.
 
int GetXSize () const
 Return the width of the block.
 
int GetYSize () const
 Return the height of the block.
 
int GetDirty () const
 Return the dirty flag.
 
void * GetDataRef (void)
 Return the data buffer.
 
GPtrDiff_t GetBlockSize () const
 Return the block size in bytes.
 
int TakeLock ()
 Take a lock and Touch().
 
int DropLockForRemovalFromStorage ()
 Drop a lock before removing the block from the band storage.
 
GDALRasterBandGetBand ()
 Accessor to source GDALRasterBand object.
 

Static Public Member Functions

static void FlushDirtyBlocks ()
 Flush all dirty blocks from cache.
 
static int FlushCacheBlock (int bDirtyBlocksOnly=FALSE)
 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 void EnterDisableDirtyBlockFlush ()
 Starts preventing dirty blocks from being flushed.
 
static void LeaveDisableDirtyBlockFlush ()
 Ends preventing dirty blocks from being flushed.
 

Friends

class GDALAbstractBandBlockCache
 

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.

And the global block manager that manages a least-recently-used list of blocks from various datasets/bands

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() [1/2]

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

GDALRasterBlock Constructor.

Normally only called from GDALRasterBand::GetLockedBlockRef().

Parameters
poBandInthe raster band used as source of raster block being constructed.
nXOffInthe horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.
nYOffInthe vertical block offset, with zero indicating the top most block, 1 the next block and so forth.

◆ GDALRasterBlock() [2/2]

GDALRasterBlock::GDALRasterBlock ( int  nXOffIn,
int  nYOffIn 
)

GDALRasterBlock Constructor (for GDALHashSetBandBlockAccess purpose)

Normally only called from GDALHashSetBandBlockAccess class. Such a block is completely non functional and only meant as being used to do a look-up in the hash set of GDALHashSetBandBlockAccess

Parameters
nXOffInthe horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.
nYOffInthe vertical block offset, with zero indicating the top most block, 1 the next block and so forth.

◆ ~GDALRasterBlock()

GDALRasterBlock::~GDALRasterBlock ( )
virtual

Block destructor.

Normally called from GDALRasterBand::FlushBlock().

Member Function Documentation

◆ Detach()

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.

◆ DropLockForRemovalFromStorage()

int GDALRasterBlock::DropLockForRemovalFromStorage ( )

Drop a lock before removing the block from the band storage.

Should only be used by GDALArrayBandBlockCache::FlushBlock() and GDALHashSetBandBlockCache::FlushBlock()

Returns
TRUE if the lock has been successfully dropped.

◆ EnterDisableDirtyBlockFlush()

void GDALRasterBlock::EnterDisableDirtyBlockFlush ( )
static

Starts preventing dirty blocks from being flushed.

This static method is used to prevent dirty blocks from being flushed. This might be useful when in a IWriteBlock() method, whose implementation can directly/indirectly cause the block cache to evict new blocks, to be recursively called on the same dataset.

This method implements a reference counter and is thread-safe.

This call must be paired with a corresponding LeaveDisableDirtyBlockFlush().

Since
GDAL 2.2.2

◆ FlushCacheBlock()

int GDALRasterBlock::FlushCacheBlock ( int  bDirtyBlocksOnly = FALSE)
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().

Parameters
bDirtyBlocksOnlyOnly flushes dirty blocks.
Returns
TRUE if successful or FALSE if no flushable block is found.

◆ FlushDirtyBlocks()

void GDALRasterBlock::FlushDirtyBlocks ( )
static

Flush all dirty blocks from cache.

This static method is normally used to recover memory and is especially useful when doing multi-threaded code that can trigger the block cache.

Due to the current design of the block cache, dirty blocks belonging to a same dataset could be pushed simultaneously to the IWriteBlock() method of that dataset from different threads, causing races.

Calling this method before that code can help workarounding that issue, in a multiple readers, one writer scenario.

Since
GDAL 2.0

◆ GetBand()

GDALRasterBand * GDALRasterBlock::GetBand ( )
inline

Accessor to source GDALRasterBand object.

Returns
source raster band of the raster block.

◆ GetBlockSize()

GPtrDiff_t GDALRasterBlock::GetBlockSize ( ) const
inline

Return the block size in bytes.

Returns
block size.

◆ GetDataRef()

void * GDALRasterBlock::GetDataRef ( void  )
inline

Return the data buffer.

Returns
data buffer

◆ GetDataType()

GDALDataType GDALRasterBlock::GetDataType ( ) const
inline

Return the data type.

Returns
data type

◆ GetDirty()

int GDALRasterBlock::GetDirty ( ) const
inline

Return the dirty flag.

Returns
dirty flag

◆ GetXOff()

int GDALRasterBlock::GetXOff ( ) const
inline

Return the x offset of the top-left corner of the block.

Returns
x offset

◆ GetXSize()

int GDALRasterBlock::GetXSize ( ) const
inline

Return the width of the block.

Returns
width

◆ GetYOff()

int GDALRasterBlock::GetYOff ( ) const
inline

Return the y offset of the top-left corner of the block.

Returns
y offset

◆ GetYSize()

int GDALRasterBlock::GetYSize ( ) const
inline

Return the height of the block.

Returns
height

◆ Internalize()

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.

◆ LeaveDisableDirtyBlockFlush()

void GDALRasterBlock::LeaveDisableDirtyBlockFlush ( )
static

Ends preventing dirty blocks from being flushed.

Undoes the effect of EnterDisableDirtyBlockFlush().

Since
GDAL 2.2.2

◆ MarkClean()

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.

◆ MarkDirty()

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.

◆ TakeLock()

int GDALRasterBlock::TakeLock ( )

Take a lock and Touch().

Should only be used by GDALArrayBandBlockCache::TryGetLockedBlockRef() and GDALHashSetBandBlockCache::TryGetLockedBlockRef()

Returns
TRUE if the lock has been successfully acquired. If FALSE, the block is being evicted by another thread, and so should be considered as invalid.

◆ Touch()

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.

◆ Write()

CPLErr GDALRasterBlock::Write ( )

Force writing of the current block, if dirty.

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

Returns
CE_None otherwise the error returned by IWriteBlock().

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