TEMPFILEOPTIONS

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

The TEMPFILEOPTIONS structure controls the temporary file options used by LEADTOOLS SDKs. TEMPFILEOPTIONS can be used with L_GetTempFileOptions and L_SetTempFileOptions to get and set the temporary file options. These options are global (all threads use the same settings).

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:

Value Meaning
L_TEMPFILEMODE_DEFAULT [0] Let LEADTOOLS pick the default mode (behavior can change from one version to another). Currently, L_TEMPFILEMODE_DEFAULT is the same as L_TEMPFILEMODE_DISKANDMEMORY.
L_TEMPFILEMODE_DISK [1] Disk only, do not use memory to back up temporary files.
L_TEMPFILEMODE_DISKANDMEMORY [2] Use Memory for small temporary files, disk for large temporary files.
L_TEMPFILEMODE_MEMORY [3] Disable disk, all temporary files should be created in memory. Some features might fail if they require temporary files on disk. The failure might be an out of memory error code or ERROR_TEMP_FILE_DISK_DISABLED.

uFlags

Flags controlling miscellaneous options. Possible values are:

Value Meaning
L_TEMPFILE_DUMPTODISKONCLOSE [0x0001] Dump temporary memory files to disk when they are closed. By default, this flag is not set and the memory-backed temporary files stay in memory. This flag is used only if uMode is L_TEMPFILEMODE_DISKANDMEMORY.

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:

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 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:

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); 
} 

Help Version 20.0.2020.4.3
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2020 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help