GDAL

cpl_virtualmem.h
Go to the documentation of this file.
1 /**********************************************************************
2 * $Id$
3 *
4 * Name: cpl_virtualmem.h
5 * Project: CPL - Common Portability Library
6 * Purpose: Virtual memory
7 * Author: Even Rouault, <even dot rouault at spatialys.com>
8 *
9 **********************************************************************
10 * Copyright (c) 2014, Even Rouault <even dot rouault at spatialys.com>
11 *
12 * Permission is hereby granted, free of charge, to any person obtaining a
13 * copy of this software and associated documentation files (the "Software"),
14 * to deal in the Software without restriction, including without limitation
15 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 * and/or sell copies of the Software, and to permit persons to whom the
17 * Software is furnished to do so, subject to the following conditions:
18 *
19 * The above copyright notice and this permission notice shall be included
20 * in all copies or substantial portions of the Software.
21 *
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
28 * DEALINGS IN THE SOFTWARE.
29 ****************************************************************************/
30
31 #ifndef CPL_VIRTUAL_MEM_INCLUDED
32 #define CPL_VIRTUAL_MEM_INCLUDED
33
34 #include <stddef.h>
35
36 #include "cpl_port.h"
37 #include "cpl_vsi.h"
38
39 CPL_C_START
40
62 typedef struct CPLVirtualMem CPLVirtualMem;
63
75 typedef void (*CPLVirtualMemCachePageCbk)(CPLVirtualMem *ctxt, size_t nOffset,
76 void *pPageToFill, size_t nToFill,
77 void *pUserData);
78
90 typedef void (*CPLVirtualMemUnCachePageCbk)(CPLVirtualMem *ctxt, size_t nOffset,
91 const void *pPageToBeEvicted,
92 size_t nToBeEvicted,
93 void *pUserData);
94
98 typedef void (*CPLVirtualMemFreeUserData)(void *pUserData);
99
101 typedef enum
102 {
105 VIRTUALMEM_READONLY,
108 VIRTUALMEM_READONLY_ENFORCED,
111 VIRTUALMEM_READWRITE
112 } CPLVirtualMemAccessMode;
113
120 size_t CPL_DLL CPLGetPageSize(void);
121
166 CPLVirtualMem CPL_DLL *
167 CPLVirtualMemNew(size_t nSize, size_t nCacheSize, size_t nPageSizeHint,
168 int bSingleThreadUsage, CPLVirtualMemAccessMode eAccessMode,
169 CPLVirtualMemCachePageCbk pfnCachePage,
170 CPLVirtualMemUnCachePageCbk pfnUnCachePage,
171 CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData);
172
178 int CPL_DLL CPLIsVirtualMemFileMapAvailable(void);
179
206 CPLVirtualMem CPL_DLL *CPLVirtualMemFileMapNew(
207 VSILFILE *fp, vsi_l_offset nOffset, vsi_l_offset nLength,
208 CPLVirtualMemAccessMode eAccessMode,
209 CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData);
210
230 CPLVirtualMem CPL_DLL *CPLVirtualMemDerivedNew(
231 CPLVirtualMem *pVMemBase, vsi_l_offset nOffset, vsi_l_offset nSize,
232 CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData);
233
245 void CPL_DLL CPLVirtualMemFree(CPLVirtualMem *ctxt);
246
262 void CPL_DLL *CPLVirtualMemGetAddr(CPLVirtualMem *ctxt);
263
271 size_t CPL_DLL CPLVirtualMemGetSize(CPLVirtualMem *ctxt);
272
280 int CPL_DLL CPLVirtualMemIsFileMapping(CPLVirtualMem *ctxt);
281
289 CPLVirtualMemAccessMode CPL_DLL CPLVirtualMemGetAccessMode(CPLVirtualMem *ctxt);
290
301 size_t CPL_DLL CPLVirtualMemGetPageSize(CPLVirtualMem *ctxt);
302
320 int CPL_DLL CPLVirtualMemIsAccessThreadSafe(CPLVirtualMem *ctxt);
321
334 void CPL_DLL CPLVirtualMemDeclareThread(CPLVirtualMem *ctxt);
335
348 void CPL_DLL CPLVirtualMemUnDeclareThread(CPLVirtualMem *ctxt);
349
367 void CPL_DLL CPLVirtualMemPin(CPLVirtualMem *ctxt, void *pAddr, size_t nSize,
368 int bWriteOp);
369
377 void CPL_DLL CPLVirtualMemManagerTerminate(void);
378
379 CPL_C_END
380
381 #endif /* CPL_VIRTUAL_MEM_INCLUDED */
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:1963
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:90
CPLVirtualMemGetSize
size_t CPLVirtualMemGetSize(CPLVirtualMem *ctxt)
Return the size of the virtual memory mapping.
Definition: cpl_virtualmem.cpp:2234
cpl_vsi.h
CPLVirtualMemManagerTerminate
void CPLVirtualMemManagerTerminate(void)
Cleanup any resource and handlers related to virtual memory.
Definition: cpl_virtualmem.cpp:1989
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:2122
CPLGetPageSize
size_t CPLGetPageSize(void)
Return the size of a page of virtual memory.
Definition: cpl_virtualmem.cpp:2139
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition: cpl_port.h:315
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:1984
VIRTUALMEM_READONLY
@ VIRTUALMEM_READONLY
Definition: cpl_virtualmem.h:105
CPLVirtualMemGetPageSize
size_t CPLVirtualMemGetPageSize(CPLVirtualMem *ctxt)
Return the page size associated to a virtual memory mapping.
Definition: cpl_virtualmem.cpp:2225
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition: cpl_port.h:319
CPLVirtualMem
struct CPLVirtualMem CPLVirtualMem
Opaque type that represents a virtual memory mapping.
Definition: cpl_virtualmem.h:62
VSIVirtualHandle
Virtual file handle.
Definition: cpl_vsi_virtual.h:61
CPLVirtualMemGetAddr
void * CPLVirtualMemGetAddr(CPLVirtualMem *ctxt)
Return the pointer to the start of a virtual memory mapping.
Definition: cpl_virtualmem.cpp:2198
CPLVirtualMemFreeUserData
void(* CPLVirtualMemFreeUserData)(void *pUserData)
Callback triggered when a virtual memory mapping is destroyed.
Definition: cpl_virtualmem.h:98
vsi_l_offset
GUIntBig vsi_l_offset
Type for a file offset.
Definition: cpl_vsi.h:146
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:2252
CPLVirtualMemIsFileMapping
int CPLVirtualMemIsFileMapping(CPLVirtualMem *ctxt)
Return if the virtual memory mapping is a direct file mapping.
Definition: cpl_virtualmem.cpp:2207
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:75
VIRTUALMEM_READONLY_ENFORCED
@ VIRTUALMEM_READONLY_ENFORCED
Definition: cpl_virtualmem.h:108
cpl_port.h
CPLIsVirtualMemFileMapAvailable
int CPLIsVirtualMemFileMapAvailable(void)
Return if virtual memory mapping of a file is available.
Definition: cpl_virtualmem.cpp:2152
VIRTUALMEM_READWRITE
@ VIRTUALMEM_READWRITE
Definition: cpl_virtualmem.h:111
CPLVirtualMemDeclareThread
void CPLVirtualMemDeclareThread(CPLVirtualMem *ctxt)
Declare that a thread will access a virtual memory mapping.
Definition: cpl_virtualmem.cpp:1976
CPLVirtualMemAccessMode
CPLVirtualMemAccessMode
Access mode of a virtual memory mapping.
Definition: cpl_virtualmem.h:101
CPLVirtualMemFree
void CPLVirtualMemFree(CPLVirtualMem *ctxt)
Free a virtual memory mapping.
Definition: cpl_virtualmem.cpp:2165
CPLVirtualMemGetAccessMode
CPLVirtualMemAccessMode CPLVirtualMemGetAccessMode(CPLVirtualMem *ctxt)
Return the access mode of the virtual memory mapping.
Definition: cpl_virtualmem.cpp:2216
CPLVirtualMemIsAccessThreadSafe
int CPLVirtualMemIsAccessThreadSafe(CPLVirtualMem *ctxt)
Return TRUE if this memory mapping can be accessed safely from concurrent threads.
Definition: cpl_virtualmem.cpp:2243
CPLVirtualMemUnDeclareThread
void CPLVirtualMemUnDeclareThread(CPLVirtualMem *ctxt)
Declare that a thread will stop accessing a virtual memory mapping.
Definition: cpl_virtualmem.cpp:1980