DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (72ee4800d415)

VCS Links

Macros

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*
** prshm.h -- NSPR Shared Memory
**
** NSPR Named Shared Memory API provides a cross-platform named
** shared-memory interface. NSPR Named Shared Memory is modeled on
** similar constructs in Unix and Windows operating systems. Shared
** memory allows multiple processes to access one or more common shared
** memory regions, using it as an inter-process communication channel.
**
** Notes on Platform Independence:
**   NSPR Named Shared Memory is built on the native services offered
**   by most platforms. The NSPR Named Shared Memory API tries to
**   provide a least common denominator interface so that it works
**   across all supported platforms. To ensure that it works everywhere,
**   some platform considerations must be accomodated and the protocol
**   for using NSPR Shared Memory API must be observed.
**
** Protocol:
**   Multiple shared memories can be created using NSPR's Shared Memory
**   feature. For each named shared memory, as defined by the name
**   given in the PR_OpenSharedMemory() call, a protocol for using the
**   shared memory API is required to ensure desired behavior. Failing
**   to follow the protocol may yield unpredictable results.
**   
**   PR_OpenSharedMemory() will create the shared memory segment, if it
**   does not already exist, or open a connection that the existing
**   shared memory segment if it already exists.
**   
**   PR_AttachSharedMemory() should be called following
**   PR_OpenSharedMemory() to map the memory segment to an address in
**   the application's address space.
**   
**   PR_AttachSharedMemory() may be called to re-map a shared memory
**   segment after detaching the same PRSharedMemory object. Be
**   sure to detach it when done.
**   
**   PR_DetachSharedMemory() should be called to un-map the shared
**   memory segment from the application's address space.
**   
**   PR_CloseSharedMemory() should be called when no further use of the
**   PRSharedMemory object is required within a process. Following a
**   call to  PR_CloseSharedMemory() the PRSharedMemory object is
**   invalid and cannot be reused.
**   
**   PR_DeleteSharedMemory() should be called before process
**   termination. After calling PR_DeleteSharedMemory() any further use
**   of the shared memory associated with the name may cause
**   unpredictable results.
**   
** Files:
**   The name passed to PR_OpenSharedMemory() should be a valid filename
**   for a unix platform. PR_OpenSharedMemory() creates file using the
**   name passed in. Some platforms may mangle the name before creating
**   the file and the shared memory.
**   
**   The unix implementation may use SysV IPC shared memory, Posix
**   shared memory, or memory mapped files; the filename may used to
**   define the namespace. On Windows, the name is significant, but
**   there is no file associated with name.
**   
**   No assumptions about the persistence of data in the named file
**   should be made. Depending on platform, the shared memory may be
**   mapped onto system paging space and be discarded at process
**   termination.
**   
**   All names provided to PR_OpenSharedMemory() should be valid
**   filename syntax or name syntax for shared memory for the target
**   platform. Referenced directories should have permissions 
**   appropriate for writing.
**
** Limits:
**   Different platforms have limits on both the number and size of
**   shared memory resources. The default system limits on some
**   platforms may be smaller than your requirements. These limits may
**   be adjusted on some platforms either via boot-time options or by
**   setting the size of the system paging space to accomodate more
**   and/or larger shared memory segment(s).
**
** Security:
**   On unix platforms, depending on implementation, contents of the
**   backing store for the shared memory can be exposed via the file
**   system. Set permissions and or access controls at create and attach
**   time to ensure you get the desired security.
**
**   On windows platforms, no special security measures are provided.
**
** Example:
**   The test case pr/tests/nameshm1.c provides an example of use as
**   well as testing the operation of NSPR's Named Shared Memory.
**
** lth. 18-Aug-1999.
*/

#ifndef prshm_h___
#define prshm_h___

#include "prtypes.h"
#include "prio.h"

PR_BEGIN_EXTERN_C

/*
** Declare opaque type PRSharedMemory.
*/
typedef struct PRSharedMemory PRSharedMemory;

/*
** FUNCTION: PR_OpenSharedMemory()
**
** DESCRIPTION:
**   PR_OpenSharedMemory() creates a new shared-memory segment or
**   associates a previously created memory segment with name.
**
**   When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
**   shared memory already exists, the function returns NULL with the
**   error set to PR_FILE_EXISTS_ERROR.
**
**   When parameter create is PR_SHM_CREATE and the shared memory
**   already exists, a handle to that memory segment is returned. If
**   the segment does not exist, it is created and a pointer to the
**   related PRSharedMemory structure is returned.
**
**   When parameter create is 0, and the shared memory exists, a
**   pointer to a PRSharedMemory is returned. If the shared memory does
**   not exist, NULL is returned with the error set to
**   PR_FILE_NOT_FOUND_ERROR.
**
** INPUTS:
**   name -- the name the shared-memory segment is known as.
**   size -- the size of the shared memory segment. 
**   flags -- Options for creating the shared memory
**   mode -- Same as is passed to PR_Open()
**
** OUTPUTS: 
**   The shared memory is allocated.
**
** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
**   NULL is returned on error. The reason for the error can be
**   retrieved via PR_GetError() and PR_GetOSError();
**
*/
NSPR_API( PRSharedMemory * )
    PR_OpenSharedMemory(
        const char *name,
        PRSize      size,
        PRIntn      flags,
        PRIntn      mode
);
/* Define values for PR_OpenShareMemory(...,create) */
#define PR_SHM_CREATE 0x1  /* create if not exist */
#define PR_SHM_EXCL   0x2  /* fail if already exists */

/*
** FUNCTION: PR_AttachSharedMemory()
**
** DESCRIPTION:
** PR_AttachSharedMemory() maps the shared-memory described by
** shm to the current process. 
**
** INPUTS: 
**   shm -- The handle returned from PR_OpenSharedMemory().
**   flags -- options for mapping the shared memory.
**   PR_SHM_READONLY causes the memory to be attached 
**   read-only.
**
** OUTPUTS:
**   On success, the shared memory segment represented by shm is mapped
**   into the process' address space.
**
** RETURNS: Address where shared memory is mapped, or NULL.
**   NULL is returned on error. The reason for the error can be
**   retrieved via PR_GetError() and PR_GetOSError();
**
**
*/
NSPR_API( void * )
    PR_AttachSharedMemory(
        PRSharedMemory *shm,
        PRIntn  flags
);
/* Define values for PR_AttachSharedMemory(...,flags) */ 
#define PR_SHM_READONLY 0x01

/*
** FUNCTION: PR_DetachSharedMemory()
**
** DESCRIPTION:
**   PR_DetachSharedMemory() detaches the shared-memory described
**   by shm. 
**
** INPUTS: 
**   shm -- The handle returned from PR_OpenSharedMemory().
**   addr -- The address at which the memory was attached.
**
** OUTPUTS:
**   The shared memory mapped to an address via a previous call to
**   PR_AttachSharedMemory() is unmapped.
**
** RETURNS: PRStatus
**
*/
NSPR_API( PRStatus )
    PR_DetachSharedMemory(
        PRSharedMemory *shm,
        void  *addr
);

/*
** FUNCTION: PR_CloseSharedMemory()
**
** DESCRIPTION:
**   PR_CloseSharedMemory() closes the shared-memory described by
**   shm.
** 
** INPUTS:
**   shm -- The handle returned from PR_OpenSharedMemory().
**
** OUTPUTS:
**   the shared memory represented by shm is closed
**
** RETURNS: PRStatus
**
*/
NSPR_API( PRStatus )
    PR_CloseSharedMemory(
        PRSharedMemory *shm
);

/*
** FUNCTION: PR_DeleteSharedMemory()
**
** DESCRIPTION:
**   The shared memory resource represented by name is released.
**
** INPUTS:
**   name -- the name the shared-memory segment
**
** OUTPUTS:
**   depending on platform, resources may be returned to the underlying
**   operating system.
**
** RETURNS: PRStatus
**
*/
NSPR_API( PRStatus )
    PR_DeleteSharedMemory( 
        const char *name
);

PR_END_EXTERN_C

#endif /* prshm_h___ */