PageRenderTime 44ms CodeModel.GetById 22ms RepoModel.GetById 0ms app.codeStats 0ms

/gecko_api/include/prshm.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 289 lines | 36 code | 12 blank | 241 comment | 0 complexity | 8cb73ceae821b1d7252b84a5bf4c743c MD5 | raw file
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4. *
  5. * The contents of this file are subject to the Mozilla Public License Version
  6. * 1.1 (the "License"); you may not use this file except in compliance with
  7. * the License. You may obtain a copy of the License at
  8. * http://www.mozilla.org/MPL/
  9. *
  10. * Software distributed under the License is distributed on an "AS IS" basis,
  11. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12. * for the specific language governing rights and limitations under the
  13. * License.
  14. *
  15. * The Original Code is the Netscape Portable Runtime (NSPR).
  16. *
  17. * The Initial Developer of the Original Code is
  18. * Netscape Communications Corporation.
  19. * Portions created by the Initial Developer are Copyright (C) 1999-2000
  20. * the Initial Developer. All Rights Reserved.
  21. *
  22. * Contributor(s):
  23. *
  24. * Alternatively, the contents of this file may be used under the terms of
  25. * either the GNU General Public License Version 2 or later (the "GPL"), or
  26. * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27. * in which case the provisions of the GPL or the LGPL are applicable instead
  28. * of those above. If you wish to allow use of your version of this file only
  29. * under the terms of either the GPL or the LGPL, and not to allow others to
  30. * use your version of this file under the terms of the MPL, indicate your
  31. * decision by deleting the provisions above and replace them with the notice
  32. * and other provisions required by the GPL or the LGPL. If you do not delete
  33. * the provisions above, a recipient may use your version of this file under
  34. * the terms of any one of the MPL, the GPL or the LGPL.
  35. *
  36. * ***** END LICENSE BLOCK ***** */
  37. /*
  38. ** prshm.h -- NSPR Shared Memory
  39. **
  40. ** NSPR Named Shared Memory API provides a cross-platform named
  41. ** shared-memory interface. NSPR Named Shared Memory is modeled on
  42. ** similar constructs in Unix and Windows operating systems. Shared
  43. ** memory allows multiple processes to access one or more common shared
  44. ** memory regions, using it as an inter-process communication channel.
  45. **
  46. ** Notes on Platform Independence:
  47. ** NSPR Named Shared Memory is built on the native services offered
  48. ** by most platforms. The NSPR Named Shared Memory API tries to
  49. ** provide a least common denominator interface so that it works
  50. ** across all supported platforms. To ensure that it works everywhere,
  51. ** some platform considerations must be accomodated and the protocol
  52. ** for using NSPR Shared Memory API must be observed.
  53. **
  54. ** Protocol:
  55. ** Multiple shared memories can be created using NSPR's Shared Memory
  56. ** feature. For each named shared memory, as defined by the name
  57. ** given in the PR_OpenSharedMemory() call, a protocol for using the
  58. ** shared memory API is required to ensure desired behavior. Failing
  59. ** to follow the protocol may yield unpredictable results.
  60. **
  61. ** PR_OpenSharedMemory() will create the shared memory segment, if it
  62. ** does not already exist, or open a connection that the existing
  63. ** shared memory segment if it already exists.
  64. **
  65. ** PR_AttachSharedMemory() should be called following
  66. ** PR_OpenSharedMemory() to map the memory segment to an address in
  67. ** the application's address space.
  68. **
  69. ** PR_AttachSharedMemory() may be called to re-map a shared memory
  70. ** segment after detaching the same PRSharedMemory object. Be
  71. ** sure to detach it when done.
  72. **
  73. ** PR_DetachSharedMemory() should be called to un-map the shared
  74. ** memory segment from the application's address space.
  75. **
  76. ** PR_CloseSharedMemory() should be called when no further use of the
  77. ** PRSharedMemory object is required within a process. Following a
  78. ** call to PR_CloseSharedMemory() the PRSharedMemory object is
  79. ** invalid and cannot be reused.
  80. **
  81. ** PR_DeleteSharedMemory() should be called before process
  82. ** termination. After calling PR_DeleteSharedMemory() any further use
  83. ** of the shared memory associated with the name may cause
  84. ** unpredictable results.
  85. **
  86. ** Files:
  87. ** The name passed to PR_OpenSharedMemory() should be a valid filename
  88. ** for a unix platform. PR_OpenSharedMemory() creates file using the
  89. ** name passed in. Some platforms may mangle the name before creating
  90. ** the file and the shared memory.
  91. **
  92. ** The unix implementation may use SysV IPC shared memory, Posix
  93. ** shared memory, or memory mapped files; the filename may used to
  94. ** define the namespace. On Windows, the name is significant, but
  95. ** there is no file associated with name.
  96. **
  97. ** No assumptions about the persistence of data in the named file
  98. ** should be made. Depending on platform, the shared memory may be
  99. ** mapped onto system paging space and be discarded at process
  100. ** termination.
  101. **
  102. ** All names provided to PR_OpenSharedMemory() should be valid
  103. ** filename syntax or name syntax for shared memory for the target
  104. ** platform. Referenced directories should have permissions
  105. ** appropriate for writing.
  106. **
  107. ** Limits:
  108. ** Different platforms have limits on both the number and size of
  109. ** shared memory resources. The default system limits on some
  110. ** platforms may be smaller than your requirements. These limits may
  111. ** be adjusted on some platforms either via boot-time options or by
  112. ** setting the size of the system paging space to accomodate more
  113. ** and/or larger shared memory segment(s).
  114. **
  115. ** Security:
  116. ** On unix platforms, depending on implementation, contents of the
  117. ** backing store for the shared memory can be exposed via the file
  118. ** system. Set permissions and or access controls at create and attach
  119. ** time to ensure you get the desired security.
  120. **
  121. ** On windows platforms, no special security measures are provided.
  122. **
  123. ** Example:
  124. ** The test case pr/tests/nameshm1.c provides an example of use as
  125. ** well as testing the operation of NSPR's Named Shared Memory.
  126. **
  127. ** lth. 18-Aug-1999.
  128. */
  129. #ifndef prshm_h___
  130. #define prshm_h___
  131. #include "prtypes.h"
  132. #include "prio.h"
  133. PR_BEGIN_EXTERN_C
  134. /*
  135. ** Declare opaque type PRSharedMemory.
  136. */
  137. typedef struct PRSharedMemory PRSharedMemory;
  138. /*
  139. ** FUNCTION: PR_OpenSharedMemory()
  140. **
  141. ** DESCRIPTION:
  142. ** PR_OpenSharedMemory() creates a new shared-memory segment or
  143. ** associates a previously created memory segment with name.
  144. **
  145. ** When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
  146. ** shared memory already exists, the function returns NULL with the
  147. ** error set to PR_FILE_EXISTS_ERROR.
  148. **
  149. ** When parameter create is PR_SHM_CREATE and the shared memory
  150. ** already exists, a handle to that memory segment is returned. If
  151. ** the segment does not exist, it is created and a pointer to the
  152. ** related PRSharedMemory structure is returned.
  153. **
  154. ** When parameter create is 0, and the shared memory exists, a
  155. ** pointer to a PRSharedMemory is returned. If the shared memory does
  156. ** not exist, NULL is returned with the error set to
  157. ** PR_FILE_NOT_FOUND_ERROR.
  158. **
  159. ** INPUTS:
  160. ** name -- the name the shared-memory segment is known as.
  161. ** size -- the size of the shared memory segment.
  162. ** flags -- Options for creating the shared memory
  163. ** mode -- Same as is passed to PR_Open()
  164. **
  165. ** OUTPUTS:
  166. ** The shared memory is allocated.
  167. **
  168. ** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
  169. ** NULL is returned on error. The reason for the error can be
  170. ** retrieved via PR_GetError() and PR_GetOSError();
  171. **
  172. */
  173. NSPR_API( PRSharedMemory * )
  174. PR_OpenSharedMemory(
  175. const char *name,
  176. PRSize size,
  177. PRIntn flags,
  178. PRIntn mode
  179. );
  180. /* Define values for PR_OpenShareMemory(...,create) */
  181. #define PR_SHM_CREATE 0x1 /* create if not exist */
  182. #define PR_SHM_EXCL 0x2 /* fail if already exists */
  183. /*
  184. ** FUNCTION: PR_AttachSharedMemory()
  185. **
  186. ** DESCRIPTION:
  187. ** PR_AttachSharedMemory() maps the shared-memory described by
  188. ** shm to the current process.
  189. **
  190. ** INPUTS:
  191. ** shm -- The handle returned from PR_OpenSharedMemory().
  192. ** flags -- options for mapping the shared memory.
  193. ** PR_SHM_READONLY causes the memory to be attached
  194. ** read-only.
  195. **
  196. ** OUTPUTS:
  197. ** On success, the shared memory segment represented by shm is mapped
  198. ** into the process' address space.
  199. **
  200. ** RETURNS: Address where shared memory is mapped, or NULL.
  201. ** NULL is returned on error. The reason for the error can be
  202. ** retrieved via PR_GetError() and PR_GetOSError();
  203. **
  204. **
  205. */
  206. NSPR_API( void * )
  207. PR_AttachSharedMemory(
  208. PRSharedMemory *shm,
  209. PRIntn flags
  210. );
  211. /* Define values for PR_AttachSharedMemory(...,flags) */
  212. #define PR_SHM_READONLY 0x01
  213. /*
  214. ** FUNCTION: PR_DetachSharedMemory()
  215. **
  216. ** DESCRIPTION:
  217. ** PR_DetachSharedMemory() detaches the shared-memory described
  218. ** by shm.
  219. **
  220. ** INPUTS:
  221. ** shm -- The handle returned from PR_OpenSharedMemory().
  222. ** addr -- The address at which the memory was attached.
  223. **
  224. ** OUTPUTS:
  225. ** The shared memory mapped to an address via a previous call to
  226. ** PR_AttachSharedMemory() is unmapped.
  227. **
  228. ** RETURNS: PRStatus
  229. **
  230. */
  231. NSPR_API( PRStatus )
  232. PR_DetachSharedMemory(
  233. PRSharedMemory *shm,
  234. void *addr
  235. );
  236. /*
  237. ** FUNCTION: PR_CloseSharedMemory()
  238. **
  239. ** DESCRIPTION:
  240. ** PR_CloseSharedMemory() closes the shared-memory described by
  241. ** shm.
  242. **
  243. ** INPUTS:
  244. ** shm -- The handle returned from PR_OpenSharedMemory().
  245. **
  246. ** OUTPUTS:
  247. ** the shared memory represented by shm is closed
  248. **
  249. ** RETURNS: PRStatus
  250. **
  251. */
  252. NSPR_API( PRStatus )
  253. PR_CloseSharedMemory(
  254. PRSharedMemory *shm
  255. );
  256. /*
  257. ** FUNCTION: PR_DeleteSharedMemory()
  258. **
  259. ** DESCRIPTION:
  260. ** The shared memory resource represented by name is released.
  261. **
  262. ** INPUTS:
  263. ** name -- the name the shared-memory segment
  264. **
  265. ** OUTPUTS:
  266. ** depending on platform, resources may be returned to the underlying
  267. ** operating system.
  268. **
  269. ** RETURNS: PRStatus
  270. **
  271. */
  272. NSPR_API( PRStatus )
  273. PR_DeleteSharedMemory(
  274. const char *name
  275. );
  276. PR_END_EXTERN_C
  277. #endif /* prshm_h___ */