TEMPFILEOPTIONS

Summary

The TEMPFILEOPTIONS structure controls the temporary file options used by LEADTOOLS SDKs. These options are global (all threads use the same settings).

Syntax

typedef struct tagTEMPFILEOPTIONS 
{ 
   L_UINT uStructSize; 
   L_TEMPFILEMODE uMode; 
   L_UINT uFlags; 
   L_UINT uMaxTotalMemSize; 
   L_UINT uMaxMemSizePerFile; 
   L_UINT uChunkMemSize; 
} TEMPFILEOPTIONS; 

Members

uStructSize

Size of this structure in bytes, for versioning. Set it to sizeof(TEMPFILEOPTIONS).

The following members are Temp File Mode

uMode

Value that indicates whether the temporary files are on disk, in memory, or a combination of disk and memory. Possible values are:

uFlags

Flags controlling miscellaneous options. Possible values are:

Temp File Size Thresholds

The following values are used only when uMode is set to L_TEMPFILEMODE_DISKANDMEMORY. They can be used to determine how much memory should be used for temporary files. In general, small files are kept in memory while big files get dumped to disk. You can specify the maximum size for one memory temporary file (uMaxMemSizePerFile) and the maximum size for all the memory temporary files (uMaxTotalMemSize).

uMaxTotalMemSize

Maximum amount of memory (in MB) to be used for all the memory temporary files, (cumulative).

uMaxMemSizePerFile

Maximum amount of memory (in MB) to be used for a single memory temporary file. Any temporary file bigger than this amount will be dumped to disk.

uChunkMemSize

Maximum number of MB in each memory chunk. Memory temporary files larger than this value will be split into several chunks. For example, if this value is set to 8, a temporary file of 20MB will be split into 3 chunks: 8 + 8 + 4 MB. This is useful for very large memory temporary files, because operating systems have a hard time allocating very large memory blocks. For example, allocating one 800MB memory chunk might fail, but allocating 50 chunks of 16MB might succeed.

Comments

LEADTOOLS sometimes needs to use temporary files for certain operations. For example, temporary files are used in the following cases:

• For tiled or disk bitmaps
• When large blocks of memory are created
• When large amounts of data need to be passed to 3rd party toolkits.

Fine control over temporary files is only available in LEADTOOLS version 20 or higher. In version 19 or earlier, all temporary files were kept on disk.

By default, LEADTOOLS keeps small temporary files in memory and large temporary files on disk. But it is possible to specify that all the temporary files should be on disk (uMode = L_TEMPFILEMODE_DISK) or that all temporary files should be kept in memory (uMode = L_TEMPFILEMODE_MEMORY).

The most common reason for using memory-only temporary file mode is in cloud applications. In some cloud environments, disk access is more expensive than memory: in such situations, a memory-only temporary file mode might make sense.

If you set uMode to L_TEMPFILEMODE_DISK, you will be unable to create disk bitmaps and the tiles in a tiled bitmaps will be in memory. In this situation, certain operations will fail; either with out-of-memory error codes or with the ERROR_TEMP_FILE_DISK_DISABLED [-1853] error code.

If disk temporary files are enabled, they will be stored in the folder set with L_SetTempDirectory. Exceptions to this rule are as follows:

• Some 3rd party libraries require files to be in a certain folder.
• Some 3rd party libraries create temporary files internally and do not offer a way to control file location.

Some functions which take this structure as a parameter require that the structure be initialized prior to the function call. To initialize the structure, set the uStructSize member to the total size, in bytes, of the structure (set the uStructSize to sizeof(TEMPFILEOPTIONS)). Functions that do not require the structure to be initialized will take the total size of the structure, in bytes, as an additional function parameter.

The uMaxTotalMemSize, uMaxMemSizePerFile and uChunkMemSize thresholds are used only in "disk and memory" mode (if uMode is L_TEMPFILEMODE_DISKANDMEMORY). They are ignored otherwise. In general, the following relationship should exist:

• uMaxTotalMemSize >= uMaxMemSizePerFile >= uChunkMemSize

If uMaxMemSizePerFile <= uChunkMemSize, then all memory temporary files will be kept as one chunk. If uMaxTotalMemSize <= uMaxMemSizePerFile, then the maximum size for one temporary file will be reduced to uMaxTotalMemSize.

The following code shows how to switch to memory-only mode:

TEMPFILEOPTIONS tempFileOptions; 
if(L_GetTempFileOptions(&tempFileOptions, sizeof(TEMPFILEOPTIONS)) == SUCCESS) 
{ 
    tempFileOptions.uMode = L_TEMPFILEMODE_MEMORY; 
    L_SetTempFileOptions(&tempFileOptions); 
    L_TEMPFILEMODE uMode = L_GetTempFileMode(); 
    assert(uMode == L_TEMPFILEMODE_MEMORY); 
} 

Usage

• L_GetTempFileOptions
• L_SetTempFileOptions