Instance_TryReuseCached function

Applies To: Implementing a custom GeoTransformer

Tries to reinitialize an existing GeoTransformer instance for caching purposes. Provides an optimized alternative to calling Instance_Discard and Instance_Create when an existing GeoTransformer needs to be initialized with different data.

This function will be called by GeoTransCore component when it has cached instances that are no longer required and can be reused. This functionality can prove itself  effective when the lifetime of many required objects is very short. One such situation occurs when computing footprints for a large number of frames.

[C]

BOOL __stdcall Instance_TryReuseCached(

HGeoTrans * hInstance, // pointer to handle of existing instance

const char * szGeoTransDef, // GeoTransformer definition string

GeoTrans_CreationFlags dwFlags // creation flags specifying how it will be used

);

[C++]

extern "C" BOOL __stdcall Instance_TryReuseCached(

HGeoTrans& hInstance, // handle of existing instance, by reference

const char * szGeoTransDef, // GeoTransformer definition string

GeoTrans_CreationFlags dwFlags // creation flags specifying how it will be used

);

Arguments

[in,out] hInstance

Pointer or reference to a handle of a valid GeoTransformer instance. Refer to the documentation of Instance_Create function for details about a handle to a GeoTransformer instance.

HGeoTrans type is defined in GeoTransCreation namespace and it is basically a HANDLE.

The given handle value may point to any type of GeoTransformer supported by your implementation. On return, this handle value can be preserved, but if changed to either point to a different instance or set to NULL, then previous instance should be discarded.

Note: It is not required to test against NULL the pointer or the value of the handle, since GeoTransCore component ensures their validity.

[in] szGeoTransDef

An XML formatted string defining the requested custom GeoTransformer. Please see the documentation of Instance_Create function for details about its content.

Note: It is not required to test against NULL since GeoTransCore component ensures the validity of the pointer.

[in] dwFlags

A flag combination specifying which functionalities are required for the reused instance. Please see Instance_Create function for details about its possible values.

GeoTrans_CreationFlags type is defined in GeoTransCreation namespace as a DWORD.

Return Value

Must return FALSE when the returned value of the hInstance parameter cannot be used as handle to the requested reinitialized GeoTransformer. Cached instance could be discarded and a new instance handle may be returned. When discarded but failed to create a new instance, hInstance parameter should point to NULL to signal removal from the cache. Do not return the same value if the handle does not point anymore to a valid GeoTransformer instance!

Reporting errors and warnings: Set both error and warning codes by calling SetLastError. GeoTransCore component will call GetLastError to retrieve the code and will treat it as an error if the function also returns FALSE, else as a warning. To learn how to provide descriptions for your custom error and warning codes, please see Error_FormatMessage function documentation. GTM_Errors_Warnings namespace enumerates some recommended codes and descriptions to be supported, from which the following would be set by this function:

Remarks

When your custom module implements multiple GeoTransformers, this function requires the means for identifying the type of each instance because its implementation has to be type safe. Since GeoTransCore component isn’t able to match the type of the cached instance with the newly requested GeoTransformer definition, your implementation must perform this test.

Exception handling: Usual considerations regarding C / C++ exception handling should be taken, with extra care on memory allocation failures and buffer overrun situations.

Versioning control: We encourage versioning control support for GeoTransformers, as described in the documentation of Instance_Create function. Here should be implemented as well.

Requirements

Example

Following sample represents a partial C++ implementation of this function:

[C++]

#include <windows.h>

#include <new>

extern "C" BOOL __stdcall Instance_TryReuseCached(

HGeoTrans& hInstance,

const char * szGeoTransDef,

GeoTrans_CreationFlags dwFlags

) {

if (geoTypeOf(szGeoTransDef) == type_CustomGeoTransformer) {

/* test existing instance type */

if (

type_CustomGeoTransformer == ((ICustomGeoTransformer*)hInstance)->Type()

) { // re-init previous instance

hInstance = (HGeoTrans)new ((void*)hInstance) CustomGeoTransformer(szGeoTransDef,dwFlags);

}

else { // discard old instance and create new one (different types)

delete (ICustomGeoTransformer*)hInstance; // discard previous instance

hInstance = (HGeoTrans)new CustomGeoTransformer(szGeoTransDef,dwFlags);

}

return TRUE;

}

/* TODO: if required, add here tests for more custom types */

SetLastError(err_unknown_class); // Unknown GeoTransformer class (unsupported).

return FALSE;

}

For a detailed example on how to implement this function, please see Custom GeoTransformer VC++ Sample.

Related Topics

See also: Instance_Create, Instance_Discard, Error_FormatMessage, GeoTransCreation, GTM_Errors_Warnings