GDAL

cpl_virtualmem.h
Go to the documentation of this file.
1/**********************************************************************
2 *
3 * Name: cpl_virtualmem.h
4 * Project: CPL - Common Portability Library
5 * Purpose: Virtual memory
6 * Author: Even Rouault, <even dot rouault at spatialys.com>
7 *
8 **********************************************************************
9 * Copyright (c) 2014, Even Rouault <even dot rouault at spatialys.com>
10 *
11 * SPDX-License-Identifier: MIT
12 ****************************************************************************/
13
14#ifndef CPL_VIRTUAL_MEM_INCLUDED
15#define CPL_VIRTUAL_MEM_INCLUDED
16
17#include <stddef.h>
18
19#include "cpl_port.h"
20#include "cpl_vsi.h"
21
22 CPL_C_START
23
45 typedef struct CPLVirtualMem CPLVirtualMem;
46
58 typedef void (*CPLVirtualMemCachePageCbk)(CPLVirtualMem *ctxt, size_t nOffset,
59 void *pPageToFill, size_t nToFill,
60 void *pUserData);
61
73 typedef void (*CPLVirtualMemUnCachePageCbk)(CPLVirtualMem *ctxt, size_t nOffset,
74 const void *pPageToBeEvicted,
75 size_t nToBeEvicted,
76 void *pUserData);
77
81 typedef void (*CPLVirtualMemFreeUserData)(void *pUserData);
82
84 typedef enum
85{
88 VIRTUALMEM_READONLY,
91 VIRTUALMEM_READONLY_ENFORCED,
94 VIRTUALMEM_READWRITE
95} CPLVirtualMemAccessMode;
96
102 size_t CPL_DLL CPLGetPageSize(void);
103
147 CPLVirtualMem CPL_DLL *
148 CPLVirtualMemNew(size_t nSize, size_t nCacheSize, size_t nPageSizeHint,
149 int bSingleThreadUsage, CPLVirtualMemAccessMode eAccessMode,
150 CPLVirtualMemCachePageCbk pfnCachePage,
151 CPLVirtualMemUnCachePageCbk pfnUnCachePage,
152 CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData);
153
158 int CPL_DLL CPLIsVirtualMemFileMapAvailable(void);
159
184 CPLVirtualMem CPL_DLL *CPLVirtualMemFileMapNew(
185 VSILFILE *fp, vsi_l_offset nOffset, vsi_l_offset nLength,
186 CPLVirtualMemAccessMode eAccessMode,
187 CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData);
188
207 CPLVirtualMem CPL_DLL *CPLVirtualMemDerivedNew(
208 CPLVirtualMem *pVMemBase, vsi_l_offset nOffset, vsi_l_offset nSize,
209 CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData);
210
221 void CPL_DLL CPLVirtualMemFree(CPLVirtualMem *ctxt);
222
237 void CPL_DLL *CPLVirtualMemGetAddr(CPLVirtualMem *ctxt);
238
245 size_t CPL_DLL CPLVirtualMemGetSize(CPLVirtualMem *ctxt);
246
253 int CPL_DLL CPLVirtualMemIsFileMapping(CPLVirtualMem *ctxt);
254
261 CPLVirtualMemAccessMode CPL_DLL CPLVirtualMemGetAccessMode(CPLVirtualMem *ctxt);
262
272 size_t CPL_DLL CPLVirtualMemGetPageSize(CPLVirtualMem *ctxt);
273
290 int CPL_DLL CPLVirtualMemIsAccessThreadSafe(CPLVirtualMem *ctxt);
291
303 void CPL_DLL CPLVirtualMemDeclareThread(CPLVirtualMem *ctxt);
304
316 void CPL_DLL CPLVirtualMemUnDeclareThread(CPLVirtualMem *ctxt);
317
334 void CPL_DLL CPLVirtualMemPin(CPLVirtualMem *ctxt, void *pAddr, size_t nSize,
335 int bWriteOp);
336
343 void CPL_DLL CPLVirtualMemManagerTerminate(void);
344
345 CPL_C_END
346
347#endif /* CPL_VIRTUAL_MEM_INCLUDED */
cpl_port.h
Core portability definitions for CPL.
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition cpl_port.h:289
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition cpl_port.h:285
CPLIsVirtualMemFileMapAvailable
int CPLIsVirtualMemFileMapAvailable(void)
Return if virtual memory mapping of a file is available.
Definition cpl_virtualmem.cpp:2136
CPLVirtualMemFileMapNew
CPLVirtualMem * CPLVirtualMemFileMapNew(VSILFILE *fp, vsi_l_offset nOffset, vsi_l_offset nLength, CPLVirtualMemAccessMode eAccessMode, CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData)
Create a new virtual memory mapping from a file.
Definition cpl_virtualmem.cpp:2106
CPLVirtualMemGetSize
size_t CPLVirtualMemGetSize(CPLVirtualMem *ctxt)
Return the size of the virtual memory mapping.
Definition cpl_virtualmem.cpp:2218
CPLVirtualMemNew
CPLVirtualMem * CPLVirtualMemNew(size_t nSize, size_t nCacheSize, size_t nPageSizeHint, int bSingleThreadUsage, CPLVirtualMemAccessMode eAccessMode, CPLVirtualMemCachePageCbk pfnCachePage, CPLVirtualMemUnCachePageCbk pfnUnCachePage, CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData)
Create a new virtual memory mapping.
Definition cpl_virtualmem.cpp:1947
CPLVirtualMemCachePageCbk
void(* CPLVirtualMemCachePageCbk)(CPLVirtualMem *ctxt, size_t nOffset, void *pPageToFill, size_t nToFill, void *pUserData)
Callback triggered when a still unmapped page of virtual memory is accessed.
Definition cpl_virtualmem.h:58
CPLVirtualMemManagerTerminate
void CPLVirtualMemManagerTerminate(void)
Cleanup any resource and handlers related to virtual memory.
Definition cpl_virtualmem.cpp:1973
CPLVirtualMemPin
void CPLVirtualMemPin(CPLVirtualMem *ctxt, void *pAddr, size_t nSize, int bWriteOp)
Make sure that a region of virtual memory will be realized.
Definition cpl_virtualmem.cpp:1968
CPLVirtualMemIsFileMapping
int CPLVirtualMemIsFileMapping(CPLVirtualMem *ctxt)
Return if the virtual memory mapping is a direct file mapping.
Definition cpl_virtualmem.cpp:2191
CPLVirtualMemGetAddr
void * CPLVirtualMemGetAddr(CPLVirtualMem *ctxt)
Return the pointer to the start of a virtual memory mapping.
Definition cpl_virtualmem.cpp:2182
CPLVirtualMemUnDeclareThread
void CPLVirtualMemUnDeclareThread(CPLVirtualMem *ctxt)
Declare that a thread will stop accessing a virtual memory mapping.
Definition cpl_virtualmem.cpp:1964
CPLVirtualMemUnCachePageCbk
void(* CPLVirtualMemUnCachePageCbk)(CPLVirtualMem *ctxt, size_t nOffset, const void *pPageToBeEvicted, size_t nToBeEvicted, void *pUserData)
Callback triggered when a dirty mapped page is going to be freed.
Definition cpl_virtualmem.h:73
CPLVirtualMemFreeUserData
void(* CPLVirtualMemFreeUserData)(void *pUserData)
Callback triggered when a virtual memory mapping is destroyed.
Definition cpl_virtualmem.h:81
CPLVirtualMemDerivedNew
CPLVirtualMem * CPLVirtualMemDerivedNew(CPLVirtualMem *pVMemBase, vsi_l_offset nOffset, vsi_l_offset nSize, CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData)
Create a new virtual memory mapping derived from an other virtual memory mapping.
Definition cpl_virtualmem.cpp:2236
CPLVirtualMemGetAccessMode
CPLVirtualMemAccessMode CPLVirtualMemGetAccessMode(CPLVirtualMem *ctxt)
Return the access mode of the virtual memory mapping.
Definition cpl_virtualmem.cpp:2200
CPLVirtualMemDeclareThread
void CPLVirtualMemDeclareThread(CPLVirtualMem *ctxt)
Declare that a thread will access a virtual memory mapping.
Definition cpl_virtualmem.cpp:1960
CPLVirtualMem
struct CPLVirtualMem CPLVirtualMem
Opaque type that represents a virtual memory mapping.
Definition cpl_virtualmem.h:45
CPLVirtualMemIsAccessThreadSafe
int CPLVirtualMemIsAccessThreadSafe(CPLVirtualMem *ctxt)
Return TRUE if this memory mapping can be accessed safely from concurrent threads.
Definition cpl_virtualmem.cpp:2227
CPLVirtualMemFree
void CPLVirtualMemFree(CPLVirtualMem *ctxt)
Free a virtual memory mapping.
Definition cpl_virtualmem.cpp:2149
CPLVirtualMemAccessMode
CPLVirtualMemAccessMode
Access mode of a virtual memory mapping.
Definition cpl_virtualmem.h:85
VIRTUALMEM_READONLY_ENFORCED
@ VIRTUALMEM_READONLY_ENFORCED
Definition cpl_virtualmem.h:91
VIRTUALMEM_READWRITE
@ VIRTUALMEM_READWRITE
Definition cpl_virtualmem.h:94
VIRTUALMEM_READONLY
@ VIRTUALMEM_READONLY
Definition cpl_virtualmem.h:88
CPLVirtualMemGetPageSize
size_t CPLVirtualMemGetPageSize(CPLVirtualMem *ctxt)
Return the page size associated to a virtual memory mapping.
Definition cpl_virtualmem.cpp:2209
CPLGetPageSize
size_t CPLGetPageSize(void)
Return the size of a page of virtual memory.
Definition cpl_virtualmem.cpp:2123
cpl_vsi.h
Standard C Covers.
vsi_l_offset
GUIntBig vsi_l_offset
Type for a file offset.
Definition cpl_vsi.h:136
VSIVirtualHandle
Virtual file handle.
Definition cpl_vsi_virtual.h:48