GDAL
Public Member Functions | Protected Member Functions | Protected Attributes
OGRMutexedDataSource Class Reference

OGRMutexedDataSource class protects all virtual methods of OGRDataSource with a mutex. More...

#include <ogrmutexeddatasource.h>

Inheritance diagram for OGRMutexedDataSource:
OGRDataSource GDALDataset GDALMajorObject

List of all members.

Public Member Functions

 OGRMutexedDataSource (OGRDataSource *poBaseDataSource, int bTakeOwnership, CPLMutex *hMutexIn, int bWrapLayersInMutexedLayer)
OGRDataSourceGetBaseDataSource ()
virtual const char * GetName ()
virtual int GetLayerCount ()
 Get the number of layers in this dataset.
virtual OGRLayerGetLayer (int)
 Fetch a layer by index.
virtual OGRLayerGetLayerByName (const char *)
 Fetch a layer by name.
virtual OGRErr DeleteLayer (int)
 Delete the indicated layer from the datasource.
virtual int TestCapability (const char *)
 Test if capability is available.
virtual OGRLayerICreateLayer (const char *pszName, OGRSpatialReference *poSpatialRef=NULL, OGRwkbGeometryType eGType=wkbUnknown, char **papszOptions=NULL)
 This method attempts to create a new layer on the dataset with the indicated name, coordinate system, geometry type.
virtual OGRLayerCopyLayer (OGRLayer *poSrcLayer, const char *pszNewName, char **papszOptions=NULL)
 Duplicate an existing layer.
virtual OGRStyleTableGetStyleTable ()
 Returns dataset style table.
virtual void SetStyleTableDirectly (OGRStyleTable *poStyleTable)
 Set dataset style table.
virtual void SetStyleTable (OGRStyleTable *poStyleTable)
 Set dataset style table.
virtual OGRLayerExecuteSQL (const char *pszStatement, OGRGeometry *poSpatialFilter, const char *pszDialect)
 Execute an SQL statement against the data store.
virtual void ReleaseResultSet (OGRLayer *poResultsSet)
 Release results of ExecuteSQL().
virtual void FlushCache ()
 Flush all write cached data to disk.
virtual OGRErr StartTransaction (int bForce=FALSE)
 For datasources which support transactions, StartTransaction creates a transaction.
virtual OGRErr CommitTransaction ()
 For datasources which support transactions, CommitTransaction commits a transaction.
virtual OGRErr RollbackTransaction ()
 For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction.
virtual char ** GetMetadata (const char *pszDomain="")
 Fetch metadata.
virtual CPLErr SetMetadata (char **papszMetadata, const char *pszDomain="")
 Set metadata.
virtual const char * GetMetadataItem (const char *pszName, const char *pszDomain="")
 Fetch single metadata item.
virtual CPLErr SetMetadataItem (const char *pszName, const char *pszValue, const char *pszDomain="")
 Set single metadata item.

Protected Member Functions

OGRLayerWrapLayerIfNecessary (OGRLayer *poLayer)

Protected Attributes

OGRDataSourcem_poBaseDataSource
int m_bHasOwnership
CPLMutex * m_hGlobalMutex
int m_bWrapLayersInMutexedLayer
std::map< OGRLayer
*, OGRMutexedLayer * > 
m_oMapLayers
std::map< OGRMutexedLayer
*, OGRLayer * > 
m_oReverseMapLayers

Detailed Description

OGRMutexedDataSource class protects all virtual methods of OGRDataSource with a mutex.

If the passed mutex is NULL, then no locking will be done.

Note that the constructors and destructors are not explictely protected by the mutex*


Member Function Documentation

For datasources which support transactions, CommitTransaction commits a transaction.

If no transaction is active, or the commit fails, will return OGRERR_FAILURE. Datasources which do not support transactions will always return OGRERR_UNSUPPORTED_OPERATION.

Depending on drivers, this may or may not abort layer sequential readings that are active.

This function is the same as the C function GDALDatasetCommitTransaction().

Returns:
OGRERR_NONE on success.
Since:
GDAL 2.0

Reimplemented from GDALDataset.

OGRLayer * OGRMutexedDataSource::CopyLayer ( OGRLayer poSrcLayer,
const char *  pszNewName,
char **  papszOptions = NULL 
) [virtual]

Duplicate an existing layer.

This method creates a new layer, duplicate the field definitions of the source layer and then duplicate each features of the source layer. The papszOptions argument can be used to control driver specific creation options. These options are normally documented in the format specific documentation. The source layer may come from another dataset.

This method is the same as the C function GDALDatasetCopyLayer() and the deprecated OGR_DS_CopyLayer().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
poSrcLayersource layer.
pszNewNamethe name of the layer to create.
papszOptionsa StringList of name=value options. Options are driver specific.
Returns:
an handle to the layer, or NULL if an error occurs.

Reimplemented from GDALDataset.

OGRErr OGRMutexedDataSource::DeleteLayer ( int  iLayer) [virtual]

Delete the indicated layer from the datasource.

If this method is supported the ODsCDeleteLayer capability will test TRUE on the GDALDataset.

This method is the same as the C function GDALDatasetDeleteLayer() and the deprecated OGR_DS_DeleteLayer().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
iLayerthe index of the layer to delete.
Returns:
OGRERR_NONE on success, or OGRERR_UNSUPPORTED_OPERATION if deleting layers is not supported for this datasource.

Reimplemented from GDALDataset.

OGRLayer * OGRMutexedDataSource::ExecuteSQL ( const char *  pszStatement,
OGRGeometry poSpatialFilter,
const char *  pszDialect 
) [virtual]

Execute an SQL statement against the data store.

The result of an SQL query is either NULL for statements that are in error, or that have no results set, or an OGRLayer pointer representing a results set from the query. Note that this OGRLayer is in addition to the layers in the data store and must be destroyed with ReleaseResultSet() before the dataset is closed (destroyed).

This method is the same as the C function GDALDatasetExecuteSQL() and the deprecated OGR_DS_ExecuteSQL().

For more information on the SQL dialect supported internally by OGR review the OGR SQL document. Some drivers (ie. Oracle and PostGIS) pass the SQL directly through to the underlying RDBMS.

Starting with OGR 1.10, the SQLITE dialect can also be used.

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
pszStatementthe SQL statement to execute.
poSpatialFiltergeometry which represents a spatial filter. Can be NULL.
pszDialectallows control of the statement dialect. If set to NULL, the OGR SQL engine will be used, except for RDBMS drivers that will use their dedicated SQL engine, unless OGRSQL is explicitly passed as the dialect. Starting with OGR 1.10, the SQLITE dialect can also be used.
Returns:
an OGRLayer containing the results of the query. Deallocate with ReleaseResultSet().

Reimplemented from GDALDataset.

void OGRMutexedDataSource::FlushCache ( void  ) [virtual]

Flush all write cached data to disk.

Any raster (or other GDAL) data written via GDAL calls, but buffered internally will be written to disk.

The default implementation of this method just calls the FlushCache() method on each of the raster bands and the SyncToDisk() method on each of the layers. Conceptionally, calling FlushCache() on a dataset should include any work that might be accomplished by calling SyncToDisk() on layers in that dataset.

Using this method does not prevent use from calling GDALClose() to properly close a dataset and ensure that important data not addressed by FlushCache() is written in the file.

This method is the same as the C function GDALFlushCache().

Reimplemented from GDALDataset.

Fetch a layer by index.

The returned layer remains owned by the GDALDataset and should not be deleted by the application.

This method is the same as the C function GDALDatasetGetLayer() and the deprecated OGR_DS_GetLayer().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
iLayera layer number between 0 and GetLayerCount()-1.
Returns:
the layer, or NULL if iLayer is out of range or an error occurs.

Reimplemented from GDALDataset.

OGRLayer * OGRMutexedDataSource::GetLayerByName ( const char *  pszName) [virtual]

Fetch a layer by name.

The returned layer remains owned by the GDALDataset and should not be deleted by the application.

This method is the same as the C function GDALDatasetGetLayerByName() and the deprecated OGR_DS_GetLayerByName().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
pszLayerNamethe layer name of the layer to fetch.
Returns:
the layer, or NULL if Layer is not found or an error occurs.

Reimplemented from GDALDataset.

Get the number of layers in this dataset.

This method is the same as the C function GDALDatasetGetLayerCount(), and the deprecated OGR_DS_GetLayerCount().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Returns:
layer count.

Reimplemented from GDALDataset.

char ** OGRMutexedDataSource::GetMetadata ( const char *  pszDomain = "") [virtual]

Fetch metadata.

The returned string list is owned by the object, and may change at any time. It is formated as a "Name=value" list with the last pointer value being NULL. Use the the CPL StringList functions such as CSLFetchNameValue() to manipulate it.

Note that relatively few formats return any metadata at this time.

This method does the same thing as the C function GDALGetMetadata().

Parameters:
pszDomainthe domain of interest. Use "" or NULL for the default domain.
Returns:
NULL or a string list.

Reimplemented from GDALMajorObject.

const char * OGRMutexedDataSource::GetMetadataItem ( const char *  pszName,
const char *  pszDomain = "" 
) [virtual]

Fetch single metadata item.

The C function GDALGetMetadataItem() does the same thing as this method.

Parameters:
pszNamethe key for the metadata item to fetch.
pszDomainthe domain to fetch for, use NULL for the default domain.
Returns:
NULL on failure to find the key, or a pointer to an internal copy of the value string on success.

Reimplemented from GDALMajorObject.

Returns dataset style table.

This method is the same as the C function GDALDatasetGetStyleTable() and the deprecated OGR_DS_GetStyleTable().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Returns:
pointer to a style table which should not be modified or freed by the caller.

Reimplemented from GDALDataset.

OGRLayer * OGRMutexedDataSource::ICreateLayer ( const char *  pszName,
OGRSpatialReference poSpatialRef = NULL,
OGRwkbGeometryType  eGType = wkbUnknown,
char **  papszOptions = NULL 
) [virtual]

This method attempts to create a new layer on the dataset with the indicated name, coordinate system, geometry type.

This method is reserved to implementation by drivers.

The papszOptions argument can be used to control driver specific creation options. These options are normally documented in the format specific documentation.

Parameters:
pszNamethe name for the new layer. This should ideally not match any existing layer on the datasource.
poSpatialRefthe coordinate system to use for the new layer, or NULL if no coordinate system is available.
eGTypethe geometry type for the layer. Use wkbUnknown if there are no constraints on the types geometry to be written.
papszOptionsa StringList of name=value options. Options are driver specific.
Returns:
NULL is returned on failure, or a new OGRLayer handle on success.
Since:
GDAL 2.0

Reimplemented from GDALDataset.

void OGRMutexedDataSource::ReleaseResultSet ( OGRLayer poResultsSet) [virtual]

Release results of ExecuteSQL().

This method should only be used to deallocate OGRLayers resulting from an ExecuteSQL() call on the same GDALDataset. Failure to deallocate a results set before destroying the GDALDataset may cause errors.

This method is the same as the C function GDALDatasetReleaseResultSet() and the deprecated OGR_DS_ReleaseResultSet().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
poResultsSetthe result of a previous ExecuteSQL() call.

Reimplemented from GDALDataset.

For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction.

If no transaction is active, or the rollback fails, will return OGRERR_FAILURE. Datasources which do not support transactions will always return OGRERR_UNSUPPORTED_OPERATION.

This function is the same as the C function GDALDatasetRollbackTransaction().

Returns:
OGRERR_NONE on success.
Since:
GDAL 2.0

Reimplemented from GDALDataset.

CPLErr OGRMutexedDataSource::SetMetadata ( char **  papszMetadataIn,
const char *  pszDomain = "" 
) [virtual]

Set metadata.

The C function GDALSetMetadata() does the same thing as this method.

Parameters:
papszMetadataInthe metadata in name=value string list format to apply.
pszDomainthe domain of interest. Use "" or NULL for the default domain.
Returns:
CE_None on success, CE_Failure on failure and CE_Warning if the metadata has been accepted, but is likely not maintained persistently by the underlying object between sessions.

Reimplemented from GDALMajorObject.

CPLErr OGRMutexedDataSource::SetMetadataItem ( const char *  pszName,
const char *  pszValue,
const char *  pszDomain = "" 
) [virtual]

Set single metadata item.

The C function GDALSetMetadataItem() does the same thing as this method.

Parameters:
pszNamethe key for the metadata item to fetch.
pszValuethe value to assign to the key.
pszDomainthe domain to set within, use NULL for the default domain.
Returns:
CE_None on success, or an error code on failure.

Reimplemented from GDALMajorObject.

void OGRMutexedDataSource::SetStyleTable ( OGRStyleTable poStyleTable) [virtual]

Set dataset style table.

This method operate exactly as SetStyleTableDirectly() except that it does not assume ownership of the passed table.

This method is the same as the C function GDALDatasetSetStyleTable() and the deprecated OGR_DS_SetStyleTable().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
poStyleTablepointer to style table to set

Reimplemented from GDALDataset.

void OGRMutexedDataSource::SetStyleTableDirectly ( OGRStyleTable poStyleTable) [virtual]

Set dataset style table.

This method operate exactly as SetStyleTable() except that it assumes ownership of the passed table.

This method is the same as the C function GDALDatasetSetStyleTableDirectly() and the deprecated OGR_DS_SetStyleTableDirectly().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
poStyleTablepointer to style table to set

Reimplemented from GDALDataset.

OGRErr OGRMutexedDataSource::StartTransaction ( int  bForce = FALSE) [virtual]

For datasources which support transactions, StartTransaction creates a transaction.

If starting the transaction fails, will return OGRERR_FAILURE. Datasources which do not support transactions will always return OGRERR_UNSUPPORTED_OPERATION.

Nested transactions are not supported.

All changes done after the start of the transaction are definitely applied in the datasource if CommitTransaction() is called. They may be cancelled by calling RollbackTransaction() instead.

At the time of writing, transactions only apply on vector layers.

Datasets that support transactions will advertize the ODsCTransactions capability. Use of transactions at dataset level is generally prefered to transactions at layer level, whose scope is rarely limited to the layer from which it was started.

In case StartTransaction() fails, neither CommitTransaction() or RollbackTransaction() should be called.

If an error occurs after a successful StartTransaction(), the whole transaction may or may not be implicitely cancelled, depending on drivers. (e.g. the PG driver will cancel it, SQLite/GPKG not). In any case, in the event of an error, an explicit call to RollbackTransaction() should be done to keep things balanced.

By default, when bForce is set to FALSE, only "efficient" transactions will be attempted. Some drivers may offer an emulation of transactions, but sometimes with significant overhead, in which case the user must explicitly allow for such an emulation by setting bForce to TRUE. Drivers that offer emulated transactions should advertize the ODsCEmulatedTransactions capability (and not ODsCTransactions).

This function is the same as the C function GDALDatasetStartTransaction().

Parameters:
bForcecan be set to TRUE if an emulation, possibly slow, of a transaction mechanism is acceptable.
Returns:
OGRERR_NONE on success.
Since:
GDAL 2.0

Reimplemented from GDALDataset.

int OGRMutexedDataSource::TestCapability ( const char *  ) [virtual]

Test if capability is available.

One of the following dataset capability names can be passed into this method, and a TRUE or FALSE value will be returned indicating whether or not the capability is available for this object.

  • ODsCCreateLayer: True if this datasource can create new layers.

  • ODsCDeleteLayer: True if this datasource can delete existing layers.

  • ODsCCreateGeomFieldAfterCreateLayer: True if the layers of this datasource support CreateGeomField() just after layer creation.

  • ODsCCurveGeometries: True if this datasource supports curve geometries.

  • ODsCTransactions: True if this datasource supports (efficient) transactions.

  • ODsCEmulatedTransactions: True if this datasource supports transactions through emulation.

The #define macro forms of the capability names should be used in preference to the strings themselves to avoid mispelling.

This method is the same as the C function GDALDatasetTestCapability() and the deprecated OGR_DS_TestCapability().

In GDAL 1.X, this method used to be in the OGRDataSource class.

Parameters:
pszCapabilitythe capability to test.
Returns:
TRUE if capability available otherwise FALSE.

Reimplemented from GDALDataset.


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

Generated for GDAL by doxygen 1.7.6.1.