anonymous_shared_memory.rst (3807B)
1 Anonymous Shared Memory 2 ======================= 3 4 This chapter describes the NSPR API for anonymous shared memory. 5 6 - `Anonymous Memory Protocol <#Anonymous_Memory_Protocol>`__ 7 - `Anonymous Shared Memory 8 Functions <#Anonymous_Shared_Memory_Functions>`__ 9 10 .. _Anonymous_Memory_Protocol: 11 12 Anonymous Memory Protocol 13 ------------------------- 14 15 NSPR provides an anonymous shared memory based on NSPR's :ref:`PRFileMap` 16 type. The anonymous file-mapped shared memory provides an inheritable 17 shared memory, as in: the child process inherits the shared memory. 18 Compare the file-mapped anonymous shared memory to to a named shared 19 memory described in prshm.h. The intent is to provide a shared memory 20 that is accessible only by parent and child processes. ... It's a 21 security thing. 22 23 Depending on the underlying platform, the file-mapped shared memory may 24 be backed by a file. ... surprise! ... On some platforms, no real file 25 backs the shared memory. On platforms where the shared memory is backed 26 by a file, the file's name in the filesystem is visible to other 27 processes for only the duration of the creation of the file, hopefully a 28 very short time. This restricts processes that do not inherit the shared 29 memory from opening the file and reading or writing its contents. 30 Further, when all processes using an anonymous shared memory terminate, 31 the backing file is deleted. ... If you are not paranoid, you're not 32 paying attention. 33 34 The file-mapped shared memory requires a protocol for the parent process 35 and child process to share the memory. NSPR provides two protocols. Use 36 one or the other; don't mix and match. 37 38 In the first protocol, the job of passing the inheritable shared memory 39 is done via helper-functions with PR_CreateProcess. In the second 40 protocol, the parent process is responsible for creating the child 41 process; the parent and child are mutually responsible for passing a 42 ``FileMap`` string. NSPR provides helper functions for extracting data 43 from the :ref:`PRFileMap` object. ... See the examples below. 44 45 Both sides should adhere strictly to the protocol for proper operation. 46 The pseudo-code below shows the use of a file-mapped shared memory by a 47 parent and child processes. In the examples, the server creates the 48 file-mapped shared memory, the client attaches to it. 49 50 .. _First_protocol: 51 52 First protocol 53 ~~~~~~~~~~~~~~ 54 55 **Server:** 56 57 .. code:: 58 59 fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 60 addr = PR_MemMap(fm); 61 attr = PR_NewProcessAttr(); 62 PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname ); 63 PR_CreateProcess(Client); 64 PR_DestroyProcessAttr(attr); 65 ... yadda ... 66 PR_MemUnmap( addr ); 67 PR_CloseFileMap(fm); 68 69 **Client:** 70 71 .. code:: 72 73 ... started by server via PR_CreateProcess() 74 fm = PR_GetInheritedFileMap( shmname ); 75 addr = PR_MemMap(fm); 76 ... yadda ... 77 PR_MemUnmap(addr); 78 PR_CloseFileMap(fm); 79 80 .. _Second_protocol: 81 82 Second protocol 83 ~~~~~~~~~~~~~~~ 84 85 **Server:** 86 87 .. code:: 88 89 fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 90 fmstring = PR_ExportFileMapAsString( fm ); 91 addr = PR_MemMap(fm); 92 ... application specific technique to pass fmstring to child 93 ... yadda ... Server uses his own magic to create child 94 PR_MemUnmap( addr ); 95 PR_CloseFileMap(fm); 96 97 **Client:** 98 99 .. code:: 100 101 ... started by server via his own magic 102 ... application specific technique to find fmstring from parent 103 fm = PR_ImportFileMapFromString( fmstring ) 104 addr = PR_MemMap(fm); 105 ... yadda ... 106 PR_MemUnmap(addr); 107 PR_CloseFileMap(fm); 108 109 .. _Anonymous_Shared_Memory_Functions: 110 111 Anonymous Shared Memory Functions 112 --------------------------------- 113 114 - :ref:`PR_OpenAnonFileMap` 115 - :ref:`PR_ProcessAttrSetInheritableFileMap` 116 - :ref:`PR_GetInheritedFileMap` 117 - :ref:`PR_ExportFileMapAsString` 118 - :ref:`PR_ImportFileMapFromString`