Thu, 22 Jan 2015 13:21:57 +0100
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
michael@0 | 1 | /* This Source Code Form is subject to the terms of the Mozilla Public |
michael@0 | 2 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
michael@0 | 3 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
michael@0 | 4 | |
michael@0 | 5 | #ifndef BASE_H |
michael@0 | 6 | #define BASE_H |
michael@0 | 7 | |
michael@0 | 8 | /* |
michael@0 | 9 | * base.h |
michael@0 | 10 | * |
michael@0 | 11 | * This header file contains basic prototypes and preprocessor |
michael@0 | 12 | * definitions used throughout nss but not available publicly. |
michael@0 | 13 | */ |
michael@0 | 14 | |
michael@0 | 15 | #ifndef BASET_H |
michael@0 | 16 | #include "baset.h" |
michael@0 | 17 | #endif /* BASET_H */ |
michael@0 | 18 | |
michael@0 | 19 | #ifndef NSSBASE_H |
michael@0 | 20 | #include "nssbase.h" |
michael@0 | 21 | #endif /* NSSBASE_H */ |
michael@0 | 22 | |
michael@0 | 23 | #include "plhash.h" |
michael@0 | 24 | |
michael@0 | 25 | PR_BEGIN_EXTERN_C |
michael@0 | 26 | |
michael@0 | 27 | /* |
michael@0 | 28 | * NSSArena |
michael@0 | 29 | * |
michael@0 | 30 | * The nonpublic methods relating to this type are: |
michael@0 | 31 | * |
michael@0 | 32 | * nssArena_Create -- constructor |
michael@0 | 33 | * nssArena_Destroy |
michael@0 | 34 | * nssArena_Mark |
michael@0 | 35 | * nssArena_Release |
michael@0 | 36 | * nssArena_Unmark |
michael@0 | 37 | * |
michael@0 | 38 | * nss_ZAlloc |
michael@0 | 39 | * nss_ZFreeIf |
michael@0 | 40 | * nss_ZRealloc |
michael@0 | 41 | * |
michael@0 | 42 | * Additionally, there are some preprocessor macros: |
michael@0 | 43 | * |
michael@0 | 44 | * nss_ZNEW |
michael@0 | 45 | * nss_ZNEWARRAY |
michael@0 | 46 | * |
michael@0 | 47 | * In debug builds, the following calls are available: |
michael@0 | 48 | * |
michael@0 | 49 | * nssArena_verifyPointer |
michael@0 | 50 | * nssArena_registerDestructor |
michael@0 | 51 | * nssArena_deregisterDestructor |
michael@0 | 52 | * |
michael@0 | 53 | * The following preprocessor macro is also always available: |
michael@0 | 54 | * |
michael@0 | 55 | * nssArena_VERIFYPOINTER |
michael@0 | 56 | * |
michael@0 | 57 | * A constant PLHashAllocOps structure is available for users |
michael@0 | 58 | * of the NSPL PLHashTable routines. |
michael@0 | 59 | * |
michael@0 | 60 | * nssArenaHashAllocOps |
michael@0 | 61 | */ |
michael@0 | 62 | |
michael@0 | 63 | /* |
michael@0 | 64 | * nssArena_Create |
michael@0 | 65 | * |
michael@0 | 66 | * This routine creates a new memory arena. This routine may return |
michael@0 | 67 | * NULL upon error, in which case it will have set an error on the |
michael@0 | 68 | * error stack. |
michael@0 | 69 | * |
michael@0 | 70 | * The error may be one of the following values: |
michael@0 | 71 | * NSS_ERROR_NO_MEMORY |
michael@0 | 72 | * |
michael@0 | 73 | * Return value: |
michael@0 | 74 | * NULL upon error |
michael@0 | 75 | * A pointer to an NSSArena upon success |
michael@0 | 76 | */ |
michael@0 | 77 | |
michael@0 | 78 | /* |
michael@0 | 79 | * XXX fgmr |
michael@0 | 80 | * Arenas can be named upon creation; this is mostly of use when |
michael@0 | 81 | * debugging. Should we expose that here, allowing an optional |
michael@0 | 82 | * "const char *name" argument? Should the public version of this |
michael@0 | 83 | * call (NSSArena_Create) have it too? |
michael@0 | 84 | */ |
michael@0 | 85 | |
michael@0 | 86 | NSS_EXTERN NSSArena * |
michael@0 | 87 | nssArena_Create |
michael@0 | 88 | ( |
michael@0 | 89 | void |
michael@0 | 90 | ); |
michael@0 | 91 | |
michael@0 | 92 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 93 | |
michael@0 | 94 | /* |
michael@0 | 95 | * nssArena_Destroy |
michael@0 | 96 | * |
michael@0 | 97 | * This routine will destroy the specified arena, freeing all memory |
michael@0 | 98 | * allocated from it. This routine returns a PRStatus value; if |
michael@0 | 99 | * successful, it will return PR_SUCCESS. If unsuccessful, it will |
michael@0 | 100 | * set an error on the error stack and return PR_FAILURE. |
michael@0 | 101 | * |
michael@0 | 102 | * The error may be one of the following values: |
michael@0 | 103 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 104 | * |
michael@0 | 105 | * Return value: |
michael@0 | 106 | * PR_SUCCESS |
michael@0 | 107 | * PR_FAILURE |
michael@0 | 108 | */ |
michael@0 | 109 | |
michael@0 | 110 | NSS_EXTERN PRStatus |
michael@0 | 111 | nssArena_Destroy |
michael@0 | 112 | ( |
michael@0 | 113 | NSSArena *arena |
michael@0 | 114 | ); |
michael@0 | 115 | |
michael@0 | 116 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 117 | |
michael@0 | 118 | /* |
michael@0 | 119 | * nssArena_Mark |
michael@0 | 120 | * |
michael@0 | 121 | * This routine "marks" the current state of an arena. Space |
michael@0 | 122 | * allocated after the arena has been marked can be freed by |
michael@0 | 123 | * releasing the arena back to the mark with nssArena_Release, |
michael@0 | 124 | * or committed by calling nssArena_Unmark. When successful, |
michael@0 | 125 | * this routine returns a valid nssArenaMark pointer. This |
michael@0 | 126 | * routine may return NULL upon error, in which case it will |
michael@0 | 127 | * have set an error on the error stack. |
michael@0 | 128 | * |
michael@0 | 129 | * The error may be one of the following values: |
michael@0 | 130 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 131 | * NSS_ERROR_NO_MEMORY |
michael@0 | 132 | * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
michael@0 | 133 | * |
michael@0 | 134 | * Return value: |
michael@0 | 135 | * NULL upon failure |
michael@0 | 136 | * An nssArenaMark pointer upon success |
michael@0 | 137 | */ |
michael@0 | 138 | |
michael@0 | 139 | NSS_EXTERN nssArenaMark * |
michael@0 | 140 | nssArena_Mark |
michael@0 | 141 | ( |
michael@0 | 142 | NSSArena *arena |
michael@0 | 143 | ); |
michael@0 | 144 | |
michael@0 | 145 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 146 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 147 | extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; |
michael@0 | 148 | |
michael@0 | 149 | /* |
michael@0 | 150 | * nssArena_Release |
michael@0 | 151 | * |
michael@0 | 152 | * This routine invalidates and releases all memory allocated from |
michael@0 | 153 | * the specified arena after the point at which the specified mark |
michael@0 | 154 | * was obtained. This routine returns a PRStatus value; if successful, |
michael@0 | 155 | * it will return PR_SUCCESS. If unsuccessful, it will set an error |
michael@0 | 156 | * on the error stack and return PR_FAILURE. |
michael@0 | 157 | * |
michael@0 | 158 | * The error may be one of the following values: |
michael@0 | 159 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 160 | * NSS_ERROR_INVALID_ARENA_MARK |
michael@0 | 161 | * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
michael@0 | 162 | * |
michael@0 | 163 | * Return value: |
michael@0 | 164 | * PR_SUCCESS |
michael@0 | 165 | * PR_FAILURE |
michael@0 | 166 | */ |
michael@0 | 167 | |
michael@0 | 168 | NSS_EXTERN PRStatus |
michael@0 | 169 | nssArena_Release |
michael@0 | 170 | ( |
michael@0 | 171 | NSSArena *arena, |
michael@0 | 172 | nssArenaMark *arenaMark |
michael@0 | 173 | ); |
michael@0 | 174 | |
michael@0 | 175 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 176 | extern const NSSError NSS_ERROR_INVALID_ARENA_MARK; |
michael@0 | 177 | |
michael@0 | 178 | /* |
michael@0 | 179 | * nssArena_Unmark |
michael@0 | 180 | * |
michael@0 | 181 | * This routine "commits" the indicated mark and any marks after |
michael@0 | 182 | * it, making them unreleasable. Note that any earlier marks can |
michael@0 | 183 | * still be released, and such a release will invalidate these |
michael@0 | 184 | * later unmarked regions. If an arena is to be safely shared by |
michael@0 | 185 | * more than one thread, all marks must be either released or |
michael@0 | 186 | * unmarked. This routine returns a PRStatus value; if successful, |
michael@0 | 187 | * it will return PR_SUCCESS. If unsuccessful, it will set an error |
michael@0 | 188 | * on the error stack and return PR_FAILURE. |
michael@0 | 189 | * |
michael@0 | 190 | * The error may be one of the following values: |
michael@0 | 191 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 192 | * NSS_ERROR_INVALID_ARENA_MARK |
michael@0 | 193 | * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
michael@0 | 194 | * |
michael@0 | 195 | * Return value: |
michael@0 | 196 | * PR_SUCCESS |
michael@0 | 197 | * PR_FAILURE |
michael@0 | 198 | */ |
michael@0 | 199 | |
michael@0 | 200 | NSS_EXTERN PRStatus |
michael@0 | 201 | nssArena_Unmark |
michael@0 | 202 | ( |
michael@0 | 203 | NSSArena *arena, |
michael@0 | 204 | nssArenaMark *arenaMark |
michael@0 | 205 | ); |
michael@0 | 206 | |
michael@0 | 207 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 208 | extern const NSSError NSS_ERROR_INVALID_ARENA_MARK; |
michael@0 | 209 | extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; |
michael@0 | 210 | |
michael@0 | 211 | #ifdef ARENA_DESTRUCTOR_LIST |
michael@0 | 212 | |
michael@0 | 213 | /* |
michael@0 | 214 | * nssArena_registerDestructor |
michael@0 | 215 | * |
michael@0 | 216 | * This routine stores a pointer to a callback and an arbitrary |
michael@0 | 217 | * pointer-sized argument in the arena, at the current point in |
michael@0 | 218 | * the mark stack. If the arena is destroyed, or an "earlier" |
michael@0 | 219 | * mark is released, then this destructor will be called at that |
michael@0 | 220 | * time. Note that the destructor will be called with the arena |
michael@0 | 221 | * locked, which means the destructor may free memory in that |
michael@0 | 222 | * arena, but it may not allocate or cause to be allocated any |
michael@0 | 223 | * memory. This callback facility was included to support our |
michael@0 | 224 | * debug-version pointer-tracker feature; overuse runs counter to |
michael@0 | 225 | * the the original intent of arenas. This routine returns a |
michael@0 | 226 | * PRStatus value; if successful, it will return PR_SUCCESS. If |
michael@0 | 227 | * unsuccessful, it will set an error on the error stack and |
michael@0 | 228 | * return PR_FAILURE. |
michael@0 | 229 | * |
michael@0 | 230 | * The error may be one of the following values: |
michael@0 | 231 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 232 | * NSS_ERROR_NO_MEMORY |
michael@0 | 233 | * |
michael@0 | 234 | * Return value: |
michael@0 | 235 | * PR_SUCCESS |
michael@0 | 236 | * PR_FAILURE |
michael@0 | 237 | */ |
michael@0 | 238 | |
michael@0 | 239 | NSS_EXTERN PRStatus |
michael@0 | 240 | nssArena_registerDestructor |
michael@0 | 241 | ( |
michael@0 | 242 | NSSArena *arena, |
michael@0 | 243 | void (*destructor)(void *argument), |
michael@0 | 244 | void *arg |
michael@0 | 245 | ); |
michael@0 | 246 | |
michael@0 | 247 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 248 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 249 | |
michael@0 | 250 | /* |
michael@0 | 251 | * nssArena_deregisterDestructor |
michael@0 | 252 | * |
michael@0 | 253 | * This routine will remove the first destructor in the specified |
michael@0 | 254 | * arena which has the specified destructor and argument values. |
michael@0 | 255 | * The destructor will not be called. This routine returns a |
michael@0 | 256 | * PRStatus value; if successful, it will return PR_SUCCESS. If |
michael@0 | 257 | * unsuccessful, it will set an error on the error stack and |
michael@0 | 258 | * return PR_FAILURE. |
michael@0 | 259 | * |
michael@0 | 260 | * The error may be one of the following values: |
michael@0 | 261 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 262 | * NSS_ERROR_NOT_FOUND |
michael@0 | 263 | * |
michael@0 | 264 | * Return value: |
michael@0 | 265 | * PR_SUCCESS |
michael@0 | 266 | * PR_FAILURE |
michael@0 | 267 | */ |
michael@0 | 268 | |
michael@0 | 269 | NSS_EXTERN PRStatus |
michael@0 | 270 | nssArena_deregisterDestructor |
michael@0 | 271 | ( |
michael@0 | 272 | NSSArena *arena, |
michael@0 | 273 | void (*destructor)(void *argument), |
michael@0 | 274 | void *arg |
michael@0 | 275 | ); |
michael@0 | 276 | |
michael@0 | 277 | extern const NSSError NSS_ERROR_INVALID_ITEM; |
michael@0 | 278 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 279 | extern const NSSError NSS_ERROR_NOT_FOUND; |
michael@0 | 280 | |
michael@0 | 281 | #endif /* ARENA_DESTRUCTOR_LIST */ |
michael@0 | 282 | |
michael@0 | 283 | /* |
michael@0 | 284 | * nss_ZAlloc |
michael@0 | 285 | * |
michael@0 | 286 | * This routine allocates and zeroes a section of memory of the |
michael@0 | 287 | * size, and returns to the caller a pointer to that memory. If |
michael@0 | 288 | * the optional arena argument is non-null, the memory will be |
michael@0 | 289 | * obtained from that arena; otherwise, the memory will be obtained |
michael@0 | 290 | * from the heap. This routine may return NULL upon error, in |
michael@0 | 291 | * which case it will have set an error upon the error stack. The |
michael@0 | 292 | * value specified for size may be zero; in which case a valid |
michael@0 | 293 | * zero-length block of memory will be allocated. This block may |
michael@0 | 294 | * be expanded by calling nss_ZRealloc. |
michael@0 | 295 | * |
michael@0 | 296 | * The error may be one of the following values: |
michael@0 | 297 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 298 | * NSS_ERROR_NO_MEMORY |
michael@0 | 299 | * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
michael@0 | 300 | * |
michael@0 | 301 | * Return value: |
michael@0 | 302 | * NULL upon error |
michael@0 | 303 | * A pointer to the new segment of zeroed memory |
michael@0 | 304 | */ |
michael@0 | 305 | |
michael@0 | 306 | NSS_EXTERN void * |
michael@0 | 307 | nss_ZAlloc |
michael@0 | 308 | ( |
michael@0 | 309 | NSSArena *arenaOpt, |
michael@0 | 310 | PRUint32 size |
michael@0 | 311 | ); |
michael@0 | 312 | |
michael@0 | 313 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 314 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 315 | extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; |
michael@0 | 316 | |
michael@0 | 317 | /* |
michael@0 | 318 | * nss_ZFreeIf |
michael@0 | 319 | * |
michael@0 | 320 | * If the specified pointer is non-null, then the region of memory |
michael@0 | 321 | * to which it points -- which must have been allocated with |
michael@0 | 322 | * nss_ZAlloc -- will be zeroed and released. This routine |
michael@0 | 323 | * returns a PRStatus value; if successful, it will return PR_SUCCESS. |
michael@0 | 324 | * If unsuccessful, it will set an error on the error stack and return |
michael@0 | 325 | * PR_FAILURE. |
michael@0 | 326 | * |
michael@0 | 327 | * The error may be one of the following values: |
michael@0 | 328 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 329 | * |
michael@0 | 330 | * Return value: |
michael@0 | 331 | * PR_SUCCESS |
michael@0 | 332 | * PR_FAILURE |
michael@0 | 333 | */ |
michael@0 | 334 | |
michael@0 | 335 | NSS_EXTERN PRStatus |
michael@0 | 336 | nss_ZFreeIf |
michael@0 | 337 | ( |
michael@0 | 338 | void *pointer |
michael@0 | 339 | ); |
michael@0 | 340 | |
michael@0 | 341 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 342 | |
michael@0 | 343 | /* |
michael@0 | 344 | * nss_ZRealloc |
michael@0 | 345 | * |
michael@0 | 346 | * This routine reallocates a block of memory obtained by calling |
michael@0 | 347 | * nss_ZAlloc or nss_ZRealloc. The portion of memory |
michael@0 | 348 | * between the new and old sizes -- which is either being newly |
michael@0 | 349 | * obtained or released -- is in either case zeroed. This routine |
michael@0 | 350 | * may return NULL upon failure, in which case it will have placed |
michael@0 | 351 | * an error on the error stack. |
michael@0 | 352 | * |
michael@0 | 353 | * The error may be one of the following values: |
michael@0 | 354 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 355 | * NSS_ERROR_NO_MEMORY |
michael@0 | 356 | * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
michael@0 | 357 | * |
michael@0 | 358 | * Return value: |
michael@0 | 359 | * NULL upon error |
michael@0 | 360 | * A pointer to the replacement segment of memory |
michael@0 | 361 | */ |
michael@0 | 362 | |
michael@0 | 363 | NSS_EXTERN void * |
michael@0 | 364 | nss_ZRealloc |
michael@0 | 365 | ( |
michael@0 | 366 | void *pointer, |
michael@0 | 367 | PRUint32 newSize |
michael@0 | 368 | ); |
michael@0 | 369 | |
michael@0 | 370 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 371 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 372 | extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; |
michael@0 | 373 | |
michael@0 | 374 | /* |
michael@0 | 375 | * nss_ZNEW |
michael@0 | 376 | * |
michael@0 | 377 | * This preprocessor macro will allocate memory for a new object |
michael@0 | 378 | * of the specified type with nss_ZAlloc, and will cast the |
michael@0 | 379 | * return value appropriately. If the optional arena argument is |
michael@0 | 380 | * non-null, the memory will be obtained from that arena; otherwise, |
michael@0 | 381 | * the memory will be obtained from the heap. This routine may |
michael@0 | 382 | * return NULL upon error, in which case it will have set an error |
michael@0 | 383 | * upon the error stack. |
michael@0 | 384 | * |
michael@0 | 385 | * The error may be one of the following values: |
michael@0 | 386 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 387 | * NSS_ERROR_NO_MEMORY |
michael@0 | 388 | * |
michael@0 | 389 | * Return value: |
michael@0 | 390 | * NULL upon error |
michael@0 | 391 | * A pointer to the new segment of zeroed memory |
michael@0 | 392 | */ |
michael@0 | 393 | |
michael@0 | 394 | /* The following line exceeds 72 characters, but emacs screws up if I split it. */ |
michael@0 | 395 | #define nss_ZNEW(arenaOpt, type) ((type *)nss_ZAlloc((arenaOpt), sizeof(type))) |
michael@0 | 396 | |
michael@0 | 397 | /* |
michael@0 | 398 | * nss_ZNEWARRAY |
michael@0 | 399 | * |
michael@0 | 400 | * This preprocessor macro will allocate memory for an array of |
michael@0 | 401 | * new objects, and will cast the return value appropriately. |
michael@0 | 402 | * If the optional arena argument is non-null, the memory will |
michael@0 | 403 | * be obtained from that arena; otherwise, the memory will be |
michael@0 | 404 | * obtained from the heap. This routine may return NULL upon |
michael@0 | 405 | * error, in which case it will have set an error upon the error |
michael@0 | 406 | * stack. The array size may be specified as zero. |
michael@0 | 407 | * |
michael@0 | 408 | * The error may be one of the following values: |
michael@0 | 409 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 410 | * NSS_ERROR_NO_MEMORY |
michael@0 | 411 | * |
michael@0 | 412 | * Return value: |
michael@0 | 413 | * NULL upon error |
michael@0 | 414 | * A pointer to the new segment of zeroed memory |
michael@0 | 415 | */ |
michael@0 | 416 | |
michael@0 | 417 | /* The following line exceeds 72 characters, but emacs screws up if I split it. */ |
michael@0 | 418 | #define nss_ZNEWARRAY(arenaOpt, type, quantity) ((type *)nss_ZAlloc((arenaOpt), sizeof(type) * (quantity))) |
michael@0 | 419 | |
michael@0 | 420 | /* |
michael@0 | 421 | * nss_ZREALLOCARRAY |
michael@0 | 422 | * |
michael@0 | 423 | * This preprocessor macro will reallocate memory for an array of |
michael@0 | 424 | * new objects, and will cast the return value appropriately. |
michael@0 | 425 | * This routine may return NULL upon error, in which case it will |
michael@0 | 426 | * have set an error upon the error stack. |
michael@0 | 427 | * |
michael@0 | 428 | * The error may be one of the following values: |
michael@0 | 429 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 430 | * NSS_ERROR_NO_MEMORY |
michael@0 | 431 | * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
michael@0 | 432 | * |
michael@0 | 433 | * Return value: |
michael@0 | 434 | * NULL upon error |
michael@0 | 435 | * A pointer to the replacement segment of memory |
michael@0 | 436 | */ |
michael@0 | 437 | #define nss_ZREALLOCARRAY(p, type, quantity) ((type *)nss_ZRealloc((p), sizeof(type) * (quantity))) |
michael@0 | 438 | |
michael@0 | 439 | /* |
michael@0 | 440 | * nssArena_verifyPointer |
michael@0 | 441 | * |
michael@0 | 442 | * This method is only present in debug builds. |
michael@0 | 443 | * |
michael@0 | 444 | * If the specified pointer is a valid pointer to an NSSArena object, |
michael@0 | 445 | * this routine will return PR_SUCCESS. Otherwise, it will put an |
michael@0 | 446 | * error on the error stack and return PR_FAILURE. |
michael@0 | 447 | * |
michael@0 | 448 | * The error may be one of the following values: |
michael@0 | 449 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 450 | * |
michael@0 | 451 | * Return value: |
michael@0 | 452 | * PR_SUCCESS if the pointer is valid |
michael@0 | 453 | * PR_FAILURE if it isn't |
michael@0 | 454 | */ |
michael@0 | 455 | |
michael@0 | 456 | #ifdef DEBUG |
michael@0 | 457 | NSS_EXTERN PRStatus |
michael@0 | 458 | nssArena_verifyPointer |
michael@0 | 459 | ( |
michael@0 | 460 | const NSSArena *arena |
michael@0 | 461 | ); |
michael@0 | 462 | |
michael@0 | 463 | extern const NSSError NSS_ERROR_INVALID_ARENA; |
michael@0 | 464 | #endif /* DEBUG */ |
michael@0 | 465 | |
michael@0 | 466 | /* |
michael@0 | 467 | * nssArena_VERIFYPOINTER |
michael@0 | 468 | * |
michael@0 | 469 | * This macro is always available. In debug builds it will call |
michael@0 | 470 | * nssArena_verifyPointer; in non-debug builds, it will merely |
michael@0 | 471 | * check that the pointer is not null. Note that in non-debug |
michael@0 | 472 | * builds it cannot place an error on the error stack. |
michael@0 | 473 | * |
michael@0 | 474 | * Return value: |
michael@0 | 475 | * PR_SUCCESS if the pointer is valid |
michael@0 | 476 | * PR_FAILURE if it isn't |
michael@0 | 477 | */ |
michael@0 | 478 | |
michael@0 | 479 | #ifdef DEBUG |
michael@0 | 480 | #define nssArena_VERIFYPOINTER(p) nssArena_verifyPointer(p) |
michael@0 | 481 | #else /* DEBUG */ |
michael@0 | 482 | /* The following line exceeds 72 characters, but emacs screws up if I split it. */ |
michael@0 | 483 | #define nssArena_VERIFYPOINTER(p) (((NSSArena *)NULL == (p))?PR_FAILURE:PR_SUCCESS) |
michael@0 | 484 | #endif /* DEBUG */ |
michael@0 | 485 | |
michael@0 | 486 | /* |
michael@0 | 487 | * Private function to be called by NSS_Shutdown to cleanup nssArena |
michael@0 | 488 | * bookkeeping. |
michael@0 | 489 | */ |
michael@0 | 490 | extern PRStatus |
michael@0 | 491 | nssArena_Shutdown(void); |
michael@0 | 492 | |
michael@0 | 493 | /* |
michael@0 | 494 | * nssArenaHashAllocOps |
michael@0 | 495 | * |
michael@0 | 496 | * This constant structure contains allocation callbacks designed for |
michael@0 | 497 | * use with the NSPL routine PL_NewHashTable. For example: |
michael@0 | 498 | * |
michael@0 | 499 | * NSSArena *hashTableArena = nssArena_Create(); |
michael@0 | 500 | * PLHashTable *t = PL_NewHashTable(n, hasher, key_compare, |
michael@0 | 501 | * value_compare, nssArenaHashAllocOps, hashTableArena); |
michael@0 | 502 | */ |
michael@0 | 503 | |
michael@0 | 504 | NSS_EXTERN_DATA PLHashAllocOps nssArenaHashAllocOps; |
michael@0 | 505 | |
michael@0 | 506 | /* |
michael@0 | 507 | * The error stack |
michael@0 | 508 | * |
michael@0 | 509 | * The nonpublic methods relating to the error stack are: |
michael@0 | 510 | * |
michael@0 | 511 | * nss_SetError |
michael@0 | 512 | * nss_ClearErrorStack |
michael@0 | 513 | */ |
michael@0 | 514 | |
michael@0 | 515 | /* |
michael@0 | 516 | * nss_SetError |
michael@0 | 517 | * |
michael@0 | 518 | * This routine places a new error code on the top of the calling |
michael@0 | 519 | * thread's error stack. Calling this routine wiht an error code |
michael@0 | 520 | * of zero will clear the error stack. |
michael@0 | 521 | */ |
michael@0 | 522 | |
michael@0 | 523 | NSS_EXTERN void |
michael@0 | 524 | nss_SetError |
michael@0 | 525 | ( |
michael@0 | 526 | PRUint32 error |
michael@0 | 527 | ); |
michael@0 | 528 | |
michael@0 | 529 | /* |
michael@0 | 530 | * nss_ClearErrorStack |
michael@0 | 531 | * |
michael@0 | 532 | * This routine clears the calling thread's error stack. |
michael@0 | 533 | */ |
michael@0 | 534 | |
michael@0 | 535 | NSS_EXTERN void |
michael@0 | 536 | nss_ClearErrorStack |
michael@0 | 537 | ( |
michael@0 | 538 | void |
michael@0 | 539 | ); |
michael@0 | 540 | |
michael@0 | 541 | /* |
michael@0 | 542 | * nss_DestroyErrorStack |
michael@0 | 543 | * |
michael@0 | 544 | * This routine frees the calling thread's error stack. |
michael@0 | 545 | */ |
michael@0 | 546 | |
michael@0 | 547 | NSS_EXTERN void |
michael@0 | 548 | nss_DestroyErrorStack |
michael@0 | 549 | ( |
michael@0 | 550 | void |
michael@0 | 551 | ); |
michael@0 | 552 | |
michael@0 | 553 | /* |
michael@0 | 554 | * NSSItem |
michael@0 | 555 | * |
michael@0 | 556 | * nssItem_Create |
michael@0 | 557 | * nssItem_Duplicate |
michael@0 | 558 | * nssItem_Equal |
michael@0 | 559 | */ |
michael@0 | 560 | |
michael@0 | 561 | NSS_EXTERN NSSItem * |
michael@0 | 562 | nssItem_Create |
michael@0 | 563 | ( |
michael@0 | 564 | NSSArena *arenaOpt, |
michael@0 | 565 | NSSItem *rvOpt, |
michael@0 | 566 | PRUint32 length, |
michael@0 | 567 | const void *data |
michael@0 | 568 | ); |
michael@0 | 569 | |
michael@0 | 570 | NSS_EXTERN void |
michael@0 | 571 | nssItem_Destroy |
michael@0 | 572 | ( |
michael@0 | 573 | NSSItem *item |
michael@0 | 574 | ); |
michael@0 | 575 | |
michael@0 | 576 | NSS_EXTERN NSSItem * |
michael@0 | 577 | nssItem_Duplicate |
michael@0 | 578 | ( |
michael@0 | 579 | NSSItem *obj, |
michael@0 | 580 | NSSArena *arenaOpt, |
michael@0 | 581 | NSSItem *rvOpt |
michael@0 | 582 | ); |
michael@0 | 583 | |
michael@0 | 584 | NSS_EXTERN PRBool |
michael@0 | 585 | nssItem_Equal |
michael@0 | 586 | ( |
michael@0 | 587 | const NSSItem *one, |
michael@0 | 588 | const NSSItem *two, |
michael@0 | 589 | PRStatus *statusOpt |
michael@0 | 590 | ); |
michael@0 | 591 | |
michael@0 | 592 | /* |
michael@0 | 593 | * NSSUTF8 |
michael@0 | 594 | * |
michael@0 | 595 | * nssUTF8_CaseIgnoreMatch |
michael@0 | 596 | * nssUTF8_Duplicate |
michael@0 | 597 | * nssUTF8_Size |
michael@0 | 598 | * nssUTF8_Length |
michael@0 | 599 | * nssUTF8_CopyIntoFixedBuffer |
michael@0 | 600 | */ |
michael@0 | 601 | |
michael@0 | 602 | /* |
michael@0 | 603 | * nssUTF8_CaseIgnoreMatch |
michael@0 | 604 | * |
michael@0 | 605 | * Returns true if the two UTF8-encoded strings pointed to by the |
michael@0 | 606 | * two specified NSSUTF8 pointers differ only in typcase. |
michael@0 | 607 | * |
michael@0 | 608 | * The error may be one of the following values: |
michael@0 | 609 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 610 | * |
michael@0 | 611 | * Return value: |
michael@0 | 612 | * PR_TRUE if the strings match, ignoring case |
michael@0 | 613 | * PR_FALSE if they don't |
michael@0 | 614 | * PR_FALSE upon error |
michael@0 | 615 | */ |
michael@0 | 616 | |
michael@0 | 617 | NSS_EXTERN PRBool |
michael@0 | 618 | nssUTF8_CaseIgnoreMatch |
michael@0 | 619 | ( |
michael@0 | 620 | const NSSUTF8 *a, |
michael@0 | 621 | const NSSUTF8 *b, |
michael@0 | 622 | PRStatus *statusOpt |
michael@0 | 623 | ); |
michael@0 | 624 | |
michael@0 | 625 | /* |
michael@0 | 626 | * nssUTF8_Duplicate |
michael@0 | 627 | * |
michael@0 | 628 | * This routine duplicates the UTF8-encoded string pointed to by the |
michael@0 | 629 | * specified NSSUTF8 pointer. If the optional arenaOpt argument is |
michael@0 | 630 | * not null, the memory required will be obtained from that arena; |
michael@0 | 631 | * otherwise, the memory required will be obtained from the heap. |
michael@0 | 632 | * A pointer to the new string will be returned. In case of error, |
michael@0 | 633 | * an error will be placed on the error stack and NULL will be |
michael@0 | 634 | * returned. |
michael@0 | 635 | * |
michael@0 | 636 | * The error may be one of the following values: |
michael@0 | 637 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 638 | * NSS_ERROR_INVALID_ARENA |
michael@0 | 639 | * NSS_ERROR_NO_MEMORY |
michael@0 | 640 | */ |
michael@0 | 641 | |
michael@0 | 642 | NSS_EXTERN NSSUTF8 * |
michael@0 | 643 | nssUTF8_Duplicate |
michael@0 | 644 | ( |
michael@0 | 645 | const NSSUTF8 *s, |
michael@0 | 646 | NSSArena *arenaOpt |
michael@0 | 647 | ); |
michael@0 | 648 | |
michael@0 | 649 | /* |
michael@0 | 650 | * nssUTF8_PrintableMatch |
michael@0 | 651 | * |
michael@0 | 652 | * Returns true if the two Printable strings pointed to by the |
michael@0 | 653 | * two specified NSSUTF8 pointers match when compared with the |
michael@0 | 654 | * rules for Printable String (leading and trailing spaces are |
michael@0 | 655 | * disregarded, extents of whitespace match irregardless of length, |
michael@0 | 656 | * and case is not significant), then PR_TRUE will be returned. |
michael@0 | 657 | * Otherwise, PR_FALSE will be returned. Upon failure, PR_FALSE |
michael@0 | 658 | * will be returned. If the optional statusOpt argument is not |
michael@0 | 659 | * NULL, then PR_SUCCESS or PR_FAILURE will be stored in that |
michael@0 | 660 | * location. |
michael@0 | 661 | * |
michael@0 | 662 | * The error may be one of the following values: |
michael@0 | 663 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 664 | * |
michael@0 | 665 | * Return value: |
michael@0 | 666 | * PR_TRUE if the strings match, ignoring case |
michael@0 | 667 | * PR_FALSE if they don't |
michael@0 | 668 | * PR_FALSE upon error |
michael@0 | 669 | */ |
michael@0 | 670 | |
michael@0 | 671 | NSS_EXTERN PRBool |
michael@0 | 672 | nssUTF8_PrintableMatch |
michael@0 | 673 | ( |
michael@0 | 674 | const NSSUTF8 *a, |
michael@0 | 675 | const NSSUTF8 *b, |
michael@0 | 676 | PRStatus *statusOpt |
michael@0 | 677 | ); |
michael@0 | 678 | |
michael@0 | 679 | /* |
michael@0 | 680 | * nssUTF8_Size |
michael@0 | 681 | * |
michael@0 | 682 | * This routine returns the length in bytes (including the terminating |
michael@0 | 683 | * null) of the UTF8-encoded string pointed to by the specified |
michael@0 | 684 | * NSSUTF8 pointer. Zero is returned on error. |
michael@0 | 685 | * |
michael@0 | 686 | * The error may be one of the following values: |
michael@0 | 687 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 688 | * NSS_ERROR_VALUE_TOO_LARGE |
michael@0 | 689 | * |
michael@0 | 690 | * Return value: |
michael@0 | 691 | * nonzero size of the string |
michael@0 | 692 | * 0 on error |
michael@0 | 693 | */ |
michael@0 | 694 | |
michael@0 | 695 | NSS_EXTERN PRUint32 |
michael@0 | 696 | nssUTF8_Size |
michael@0 | 697 | ( |
michael@0 | 698 | const NSSUTF8 *s, |
michael@0 | 699 | PRStatus *statusOpt |
michael@0 | 700 | ); |
michael@0 | 701 | |
michael@0 | 702 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 703 | extern const NSSError NSS_ERROR_VALUE_TOO_LARGE; |
michael@0 | 704 | |
michael@0 | 705 | /* |
michael@0 | 706 | * nssUTF8_Length |
michael@0 | 707 | * |
michael@0 | 708 | * This routine returns the length in characters (not including the |
michael@0 | 709 | * terminating null) of the UTF8-encoded string pointed to by the |
michael@0 | 710 | * specified NSSUTF8 pointer. |
michael@0 | 711 | * |
michael@0 | 712 | * The error may be one of the following values: |
michael@0 | 713 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 714 | * NSS_ERROR_VALUE_TOO_LARGE |
michael@0 | 715 | * NSS_ERROR_INVALID_STRING |
michael@0 | 716 | * |
michael@0 | 717 | * Return value: |
michael@0 | 718 | * length of the string (which may be zero) |
michael@0 | 719 | * 0 on error |
michael@0 | 720 | */ |
michael@0 | 721 | |
michael@0 | 722 | NSS_EXTERN PRUint32 |
michael@0 | 723 | nssUTF8_Length |
michael@0 | 724 | ( |
michael@0 | 725 | const NSSUTF8 *s, |
michael@0 | 726 | PRStatus *statusOpt |
michael@0 | 727 | ); |
michael@0 | 728 | |
michael@0 | 729 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 730 | extern const NSSError NSS_ERROR_VALUE_TOO_LARGE; |
michael@0 | 731 | extern const NSSError NSS_ERROR_INVALID_STRING; |
michael@0 | 732 | |
michael@0 | 733 | /* |
michael@0 | 734 | * nssUTF8_Create |
michael@0 | 735 | * |
michael@0 | 736 | * This routine creates a UTF8 string from a string in some other |
michael@0 | 737 | * format. Some types of string may include embedded null characters, |
michael@0 | 738 | * so for them the length parameter must be used. For string types |
michael@0 | 739 | * that are null-terminated, the length parameter is optional; if it |
michael@0 | 740 | * is zero, it will be ignored. If the optional arena argument is |
michael@0 | 741 | * non-null, the memory used for the new string will be obtained from |
michael@0 | 742 | * that arena, otherwise it will be obtained from the heap. This |
michael@0 | 743 | * routine may return NULL upon error, in which case it will have |
michael@0 | 744 | * placed an error on the error stack. |
michael@0 | 745 | * |
michael@0 | 746 | * The error may be one of the following: |
michael@0 | 747 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 748 | * NSS_ERROR_NO_MEMORY |
michael@0 | 749 | * NSS_ERROR_UNSUPPORTED_TYPE |
michael@0 | 750 | * |
michael@0 | 751 | * Return value: |
michael@0 | 752 | * NULL upon error |
michael@0 | 753 | * A non-null pointer to a new UTF8 string otherwise |
michael@0 | 754 | */ |
michael@0 | 755 | |
michael@0 | 756 | NSS_EXTERN NSSUTF8 * |
michael@0 | 757 | nssUTF8_Create |
michael@0 | 758 | ( |
michael@0 | 759 | NSSArena *arenaOpt, |
michael@0 | 760 | nssStringType type, |
michael@0 | 761 | const void *inputString, |
michael@0 | 762 | PRUint32 size /* in bytes, not characters */ |
michael@0 | 763 | ); |
michael@0 | 764 | |
michael@0 | 765 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 766 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 767 | extern const NSSError NSS_ERROR_UNSUPPORTED_TYPE; |
michael@0 | 768 | |
michael@0 | 769 | NSS_EXTERN NSSItem * |
michael@0 | 770 | nssUTF8_GetEncoding |
michael@0 | 771 | ( |
michael@0 | 772 | NSSArena *arenaOpt, |
michael@0 | 773 | NSSItem *rvOpt, |
michael@0 | 774 | nssStringType type, |
michael@0 | 775 | NSSUTF8 *string |
michael@0 | 776 | ); |
michael@0 | 777 | |
michael@0 | 778 | /* |
michael@0 | 779 | * nssUTF8_CopyIntoFixedBuffer |
michael@0 | 780 | * |
michael@0 | 781 | * This will copy a UTF8 string into a fixed-length buffer, making |
michael@0 | 782 | * sure that the all characters are valid. Any remaining space will |
michael@0 | 783 | * be padded with the specified ASCII character, typically either |
michael@0 | 784 | * null or space. |
michael@0 | 785 | * |
michael@0 | 786 | * Blah, blah, blah. |
michael@0 | 787 | */ |
michael@0 | 788 | |
michael@0 | 789 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 790 | extern const NSSError NSS_ERROR_INVALID_ARGUMENT; |
michael@0 | 791 | |
michael@0 | 792 | NSS_EXTERN PRStatus |
michael@0 | 793 | nssUTF8_CopyIntoFixedBuffer |
michael@0 | 794 | ( |
michael@0 | 795 | NSSUTF8 *string, |
michael@0 | 796 | char *buffer, |
michael@0 | 797 | PRUint32 bufferSize, |
michael@0 | 798 | char pad |
michael@0 | 799 | ); |
michael@0 | 800 | |
michael@0 | 801 | /* |
michael@0 | 802 | * nssUTF8_Equal |
michael@0 | 803 | * |
michael@0 | 804 | */ |
michael@0 | 805 | |
michael@0 | 806 | NSS_EXTERN PRBool |
michael@0 | 807 | nssUTF8_Equal |
michael@0 | 808 | ( |
michael@0 | 809 | const NSSUTF8 *a, |
michael@0 | 810 | const NSSUTF8 *b, |
michael@0 | 811 | PRStatus *statusOpt |
michael@0 | 812 | ); |
michael@0 | 813 | |
michael@0 | 814 | /* |
michael@0 | 815 | * nssList |
michael@0 | 816 | * |
michael@0 | 817 | * The goal is to provide a simple, optionally threadsafe, linked list |
michael@0 | 818 | * class. Since NSS did not seem to use the circularity of PRCList |
michael@0 | 819 | * much before, this provides a list that appears to be a linear, |
michael@0 | 820 | * NULL-terminated list. |
michael@0 | 821 | */ |
michael@0 | 822 | |
michael@0 | 823 | /* |
michael@0 | 824 | * nssList_Create |
michael@0 | 825 | * |
michael@0 | 826 | * If threadsafe is true, the list will be locked during modifications |
michael@0 | 827 | * and traversals. |
michael@0 | 828 | */ |
michael@0 | 829 | NSS_EXTERN nssList * |
michael@0 | 830 | nssList_Create |
michael@0 | 831 | ( |
michael@0 | 832 | NSSArena *arenaOpt, |
michael@0 | 833 | PRBool threadSafe |
michael@0 | 834 | ); |
michael@0 | 835 | |
michael@0 | 836 | /* |
michael@0 | 837 | * nssList_Destroy |
michael@0 | 838 | */ |
michael@0 | 839 | NSS_EXTERN PRStatus |
michael@0 | 840 | nssList_Destroy |
michael@0 | 841 | ( |
michael@0 | 842 | nssList *list |
michael@0 | 843 | ); |
michael@0 | 844 | |
michael@0 | 845 | NSS_EXTERN void |
michael@0 | 846 | nssList_Clear |
michael@0 | 847 | ( |
michael@0 | 848 | nssList *list, |
michael@0 | 849 | nssListElementDestructorFunc destructor |
michael@0 | 850 | ); |
michael@0 | 851 | |
michael@0 | 852 | /* |
michael@0 | 853 | * nssList_SetCompareFunction |
michael@0 | 854 | * |
michael@0 | 855 | * By default, two list elements will be compared by comparing their |
michael@0 | 856 | * data pointers. By setting this function, the user can control |
michael@0 | 857 | * how elements are compared. |
michael@0 | 858 | */ |
michael@0 | 859 | NSS_EXTERN void |
michael@0 | 860 | nssList_SetCompareFunction |
michael@0 | 861 | ( |
michael@0 | 862 | nssList *list, |
michael@0 | 863 | nssListCompareFunc compareFunc |
michael@0 | 864 | ); |
michael@0 | 865 | |
michael@0 | 866 | /* |
michael@0 | 867 | * nssList_SetSortFunction |
michael@0 | 868 | * |
michael@0 | 869 | * Sort function to use for an ordered list. |
michael@0 | 870 | */ |
michael@0 | 871 | NSS_EXTERN void |
michael@0 | 872 | nssList_SetSortFunction |
michael@0 | 873 | ( |
michael@0 | 874 | nssList *list, |
michael@0 | 875 | nssListSortFunc sortFunc |
michael@0 | 876 | ); |
michael@0 | 877 | |
michael@0 | 878 | /* |
michael@0 | 879 | * nssList_Add |
michael@0 | 880 | */ |
michael@0 | 881 | NSS_EXTERN PRStatus |
michael@0 | 882 | nssList_Add |
michael@0 | 883 | ( |
michael@0 | 884 | nssList *list, |
michael@0 | 885 | void *data |
michael@0 | 886 | ); |
michael@0 | 887 | |
michael@0 | 888 | /* |
michael@0 | 889 | * nssList_AddUnique |
michael@0 | 890 | * |
michael@0 | 891 | * This will use the compare function to see if the element is already |
michael@0 | 892 | * in the list. |
michael@0 | 893 | */ |
michael@0 | 894 | NSS_EXTERN PRStatus |
michael@0 | 895 | nssList_AddUnique |
michael@0 | 896 | ( |
michael@0 | 897 | nssList *list, |
michael@0 | 898 | void *data |
michael@0 | 899 | ); |
michael@0 | 900 | |
michael@0 | 901 | /* |
michael@0 | 902 | * nssList_Remove |
michael@0 | 903 | * |
michael@0 | 904 | * Uses the compare function to locate the element and remove it. |
michael@0 | 905 | */ |
michael@0 | 906 | NSS_EXTERN PRStatus |
michael@0 | 907 | nssList_Remove(nssList *list, void *data); |
michael@0 | 908 | |
michael@0 | 909 | /* |
michael@0 | 910 | * nssList_Get |
michael@0 | 911 | * |
michael@0 | 912 | * Uses the compare function to locate an element. Also serves as |
michael@0 | 913 | * nssList_Exists. |
michael@0 | 914 | */ |
michael@0 | 915 | NSS_EXTERN void * |
michael@0 | 916 | nssList_Get |
michael@0 | 917 | ( |
michael@0 | 918 | nssList *list, |
michael@0 | 919 | void *data |
michael@0 | 920 | ); |
michael@0 | 921 | |
michael@0 | 922 | /* |
michael@0 | 923 | * nssList_Count |
michael@0 | 924 | */ |
michael@0 | 925 | NSS_EXTERN PRUint32 |
michael@0 | 926 | nssList_Count |
michael@0 | 927 | ( |
michael@0 | 928 | nssList *list |
michael@0 | 929 | ); |
michael@0 | 930 | |
michael@0 | 931 | /* |
michael@0 | 932 | * nssList_GetArray |
michael@0 | 933 | * |
michael@0 | 934 | * Fill rvArray, up to maxElements, with elements in the list. The |
michael@0 | 935 | * array is NULL-terminated, so its allocated size must be maxElements + 1. |
michael@0 | 936 | */ |
michael@0 | 937 | NSS_EXTERN PRStatus |
michael@0 | 938 | nssList_GetArray |
michael@0 | 939 | ( |
michael@0 | 940 | nssList *list, |
michael@0 | 941 | void **rvArray, |
michael@0 | 942 | PRUint32 maxElements |
michael@0 | 943 | ); |
michael@0 | 944 | |
michael@0 | 945 | /* |
michael@0 | 946 | * nssList_CreateIterator |
michael@0 | 947 | * |
michael@0 | 948 | * Create an iterator for list traversal. |
michael@0 | 949 | */ |
michael@0 | 950 | NSS_EXTERN nssListIterator * |
michael@0 | 951 | nssList_CreateIterator |
michael@0 | 952 | ( |
michael@0 | 953 | nssList *list |
michael@0 | 954 | ); |
michael@0 | 955 | |
michael@0 | 956 | NSS_EXTERN nssList * |
michael@0 | 957 | nssList_Clone |
michael@0 | 958 | ( |
michael@0 | 959 | nssList *list |
michael@0 | 960 | ); |
michael@0 | 961 | |
michael@0 | 962 | /* |
michael@0 | 963 | * nssListIterator_Destroy |
michael@0 | 964 | */ |
michael@0 | 965 | NSS_EXTERN void |
michael@0 | 966 | nssListIterator_Destroy |
michael@0 | 967 | ( |
michael@0 | 968 | nssListIterator *iter |
michael@0 | 969 | ); |
michael@0 | 970 | |
michael@0 | 971 | /* |
michael@0 | 972 | * nssListIterator_Start |
michael@0 | 973 | * |
michael@0 | 974 | * Begin a list iteration. After this call, if the list is threadSafe, |
michael@0 | 975 | * the list is *locked*. |
michael@0 | 976 | */ |
michael@0 | 977 | NSS_EXTERN void * |
michael@0 | 978 | nssListIterator_Start |
michael@0 | 979 | ( |
michael@0 | 980 | nssListIterator *iter |
michael@0 | 981 | ); |
michael@0 | 982 | |
michael@0 | 983 | /* |
michael@0 | 984 | * nssListIterator_Next |
michael@0 | 985 | * |
michael@0 | 986 | * Continue a list iteration. |
michael@0 | 987 | */ |
michael@0 | 988 | NSS_EXTERN void * |
michael@0 | 989 | nssListIterator_Next |
michael@0 | 990 | ( |
michael@0 | 991 | nssListIterator *iter |
michael@0 | 992 | ); |
michael@0 | 993 | |
michael@0 | 994 | /* |
michael@0 | 995 | * nssListIterator_Finish |
michael@0 | 996 | * |
michael@0 | 997 | * Complete a list iteration. This *must* be called in order for the |
michael@0 | 998 | * lock to be released. |
michael@0 | 999 | */ |
michael@0 | 1000 | NSS_EXTERN PRStatus |
michael@0 | 1001 | nssListIterator_Finish |
michael@0 | 1002 | ( |
michael@0 | 1003 | nssListIterator *iter |
michael@0 | 1004 | ); |
michael@0 | 1005 | |
michael@0 | 1006 | /* |
michael@0 | 1007 | * nssHash |
michael@0 | 1008 | * |
michael@0 | 1009 | * nssHash_Create |
michael@0 | 1010 | * nssHash_Destroy |
michael@0 | 1011 | * nssHash_Add |
michael@0 | 1012 | * nssHash_Remove |
michael@0 | 1013 | * nssHash_Count |
michael@0 | 1014 | * nssHash_Exists |
michael@0 | 1015 | * nssHash_Lookup |
michael@0 | 1016 | * nssHash_Iterate |
michael@0 | 1017 | */ |
michael@0 | 1018 | |
michael@0 | 1019 | /* |
michael@0 | 1020 | * nssHash_Create |
michael@0 | 1021 | * |
michael@0 | 1022 | */ |
michael@0 | 1023 | |
michael@0 | 1024 | NSS_EXTERN nssHash * |
michael@0 | 1025 | nssHash_Create |
michael@0 | 1026 | ( |
michael@0 | 1027 | NSSArena *arenaOpt, |
michael@0 | 1028 | PRUint32 numBuckets, |
michael@0 | 1029 | PLHashFunction keyHash, |
michael@0 | 1030 | PLHashComparator keyCompare, |
michael@0 | 1031 | PLHashComparator valueCompare |
michael@0 | 1032 | ); |
michael@0 | 1033 | |
michael@0 | 1034 | NSS_EXTERN nssHash * |
michael@0 | 1035 | nssHash_CreatePointer |
michael@0 | 1036 | ( |
michael@0 | 1037 | NSSArena *arenaOpt, |
michael@0 | 1038 | PRUint32 numBuckets |
michael@0 | 1039 | ); |
michael@0 | 1040 | |
michael@0 | 1041 | NSS_EXTERN nssHash * |
michael@0 | 1042 | nssHash_CreateString |
michael@0 | 1043 | ( |
michael@0 | 1044 | NSSArena *arenaOpt, |
michael@0 | 1045 | PRUint32 numBuckets |
michael@0 | 1046 | ); |
michael@0 | 1047 | |
michael@0 | 1048 | NSS_EXTERN nssHash * |
michael@0 | 1049 | nssHash_CreateItem |
michael@0 | 1050 | ( |
michael@0 | 1051 | NSSArena *arenaOpt, |
michael@0 | 1052 | PRUint32 numBuckets |
michael@0 | 1053 | ); |
michael@0 | 1054 | |
michael@0 | 1055 | /* |
michael@0 | 1056 | * nssHash_Destroy |
michael@0 | 1057 | * |
michael@0 | 1058 | */ |
michael@0 | 1059 | NSS_EXTERN void |
michael@0 | 1060 | nssHash_Destroy |
michael@0 | 1061 | ( |
michael@0 | 1062 | nssHash *hash |
michael@0 | 1063 | ); |
michael@0 | 1064 | |
michael@0 | 1065 | /* |
michael@0 | 1066 | * nssHash_Add |
michael@0 | 1067 | * |
michael@0 | 1068 | */ |
michael@0 | 1069 | |
michael@0 | 1070 | extern const NSSError NSS_ERROR_HASH_COLLISION; |
michael@0 | 1071 | |
michael@0 | 1072 | NSS_EXTERN PRStatus |
michael@0 | 1073 | nssHash_Add |
michael@0 | 1074 | ( |
michael@0 | 1075 | nssHash *hash, |
michael@0 | 1076 | const void *key, |
michael@0 | 1077 | const void *value |
michael@0 | 1078 | ); |
michael@0 | 1079 | |
michael@0 | 1080 | /* |
michael@0 | 1081 | * nssHash_Remove |
michael@0 | 1082 | * |
michael@0 | 1083 | */ |
michael@0 | 1084 | NSS_EXTERN void |
michael@0 | 1085 | nssHash_Remove |
michael@0 | 1086 | ( |
michael@0 | 1087 | nssHash *hash, |
michael@0 | 1088 | const void *it |
michael@0 | 1089 | ); |
michael@0 | 1090 | |
michael@0 | 1091 | /* |
michael@0 | 1092 | * nssHash_Count |
michael@0 | 1093 | * |
michael@0 | 1094 | */ |
michael@0 | 1095 | NSS_EXTERN PRUint32 |
michael@0 | 1096 | nssHash_Count |
michael@0 | 1097 | ( |
michael@0 | 1098 | nssHash *hash |
michael@0 | 1099 | ); |
michael@0 | 1100 | |
michael@0 | 1101 | /* |
michael@0 | 1102 | * nssHash_Exists |
michael@0 | 1103 | * |
michael@0 | 1104 | */ |
michael@0 | 1105 | NSS_EXTERN PRBool |
michael@0 | 1106 | nssHash_Exists |
michael@0 | 1107 | ( |
michael@0 | 1108 | nssHash *hash, |
michael@0 | 1109 | const void *it |
michael@0 | 1110 | ); |
michael@0 | 1111 | |
michael@0 | 1112 | /* |
michael@0 | 1113 | * nssHash_Lookup |
michael@0 | 1114 | * |
michael@0 | 1115 | */ |
michael@0 | 1116 | NSS_EXTERN void * |
michael@0 | 1117 | nssHash_Lookup |
michael@0 | 1118 | ( |
michael@0 | 1119 | nssHash *hash, |
michael@0 | 1120 | const void *it |
michael@0 | 1121 | ); |
michael@0 | 1122 | |
michael@0 | 1123 | /* |
michael@0 | 1124 | * nssHash_Iterate |
michael@0 | 1125 | * |
michael@0 | 1126 | */ |
michael@0 | 1127 | NSS_EXTERN void |
michael@0 | 1128 | nssHash_Iterate |
michael@0 | 1129 | ( |
michael@0 | 1130 | nssHash *hash, |
michael@0 | 1131 | nssHashIterator fcn, |
michael@0 | 1132 | void *closure |
michael@0 | 1133 | ); |
michael@0 | 1134 | |
michael@0 | 1135 | |
michael@0 | 1136 | /* |
michael@0 | 1137 | * nssPointerTracker |
michael@0 | 1138 | * |
michael@0 | 1139 | * This type and these methods are only present in debug builds. |
michael@0 | 1140 | * |
michael@0 | 1141 | * The nonpublic methods relating to this type are: |
michael@0 | 1142 | * |
michael@0 | 1143 | * nssPointerTracker_initialize |
michael@0 | 1144 | * nssPointerTracker_finalize |
michael@0 | 1145 | * nssPointerTracker_add |
michael@0 | 1146 | * nssPointerTracker_remove |
michael@0 | 1147 | * nssPointerTracker_verify |
michael@0 | 1148 | */ |
michael@0 | 1149 | |
michael@0 | 1150 | /* |
michael@0 | 1151 | * nssPointerTracker_initialize |
michael@0 | 1152 | * |
michael@0 | 1153 | * This method is only present in debug builds. |
michael@0 | 1154 | * |
michael@0 | 1155 | * This routine initializes an nssPointerTracker object. Note that |
michael@0 | 1156 | * the object must have been declared *static* to guarantee that it |
michael@0 | 1157 | * is in a zeroed state initially. This routine is idempotent, and |
michael@0 | 1158 | * may even be safely called by multiple threads simultaneously with |
michael@0 | 1159 | * the same argument. This routine returns a PRStatus value; if |
michael@0 | 1160 | * successful, it will return PR_SUCCESS. On failure it will set an |
michael@0 | 1161 | * error on the error stack and return PR_FAILURE. |
michael@0 | 1162 | * |
michael@0 | 1163 | * The error may be one of the following values: |
michael@0 | 1164 | * NSS_ERROR_NO_MEMORY |
michael@0 | 1165 | * |
michael@0 | 1166 | * Return value: |
michael@0 | 1167 | * PR_SUCCESS |
michael@0 | 1168 | * PR_FAILURE |
michael@0 | 1169 | */ |
michael@0 | 1170 | |
michael@0 | 1171 | #ifdef DEBUG |
michael@0 | 1172 | NSS_EXTERN PRStatus |
michael@0 | 1173 | nssPointerTracker_initialize |
michael@0 | 1174 | ( |
michael@0 | 1175 | nssPointerTracker *tracker |
michael@0 | 1176 | ); |
michael@0 | 1177 | |
michael@0 | 1178 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 1179 | #endif /* DEBUG */ |
michael@0 | 1180 | |
michael@0 | 1181 | /* |
michael@0 | 1182 | * nssPointerTracker_finalize |
michael@0 | 1183 | * |
michael@0 | 1184 | * This method is only present in debug builds. |
michael@0 | 1185 | * |
michael@0 | 1186 | * This routine returns the nssPointerTracker object to the pre- |
michael@0 | 1187 | * initialized state, releasing all resources used by the object. |
michael@0 | 1188 | * It will *NOT* destroy the objects being tracked by the pointer |
michael@0 | 1189 | * (should any remain), and therefore cannot be used to "sweep up" |
michael@0 | 1190 | * remaining objects. This routine returns a PRStatus value; if |
michael@0 | 1191 | * successful, it will return PR_SUCCES. On failure it will set an |
michael@0 | 1192 | * error on the error stack and return PR_FAILURE. If any objects |
michael@0 | 1193 | * remain in the tracker when it is finalized, that will be treated |
michael@0 | 1194 | * as an error. |
michael@0 | 1195 | * |
michael@0 | 1196 | * The error may be one of the following values: |
michael@0 | 1197 | * NSS_ERROR_TRACKER_NOT_EMPTY |
michael@0 | 1198 | * |
michael@0 | 1199 | * Return value: |
michael@0 | 1200 | * PR_SUCCESS |
michael@0 | 1201 | * PR_FAILURE |
michael@0 | 1202 | */ |
michael@0 | 1203 | |
michael@0 | 1204 | #ifdef DEBUG |
michael@0 | 1205 | NSS_EXTERN PRStatus |
michael@0 | 1206 | nssPointerTracker_finalize |
michael@0 | 1207 | ( |
michael@0 | 1208 | nssPointerTracker *tracker |
michael@0 | 1209 | ); |
michael@0 | 1210 | |
michael@0 | 1211 | extern const NSSError NSS_ERROR_TRACKER_NOT_EMPTY; |
michael@0 | 1212 | #endif /* DEBUG */ |
michael@0 | 1213 | |
michael@0 | 1214 | /* |
michael@0 | 1215 | * nssPointerTracker_add |
michael@0 | 1216 | * |
michael@0 | 1217 | * This method is only present in debug builds. |
michael@0 | 1218 | * |
michael@0 | 1219 | * This routine adds the specified pointer to the nssPointerTracker |
michael@0 | 1220 | * object. It should be called in constructor objects to register |
michael@0 | 1221 | * new valid objects. The nssPointerTracker is threadsafe, but this |
michael@0 | 1222 | * call is not idempotent. This routine returns a PRStatus value; |
michael@0 | 1223 | * if successful it will return PR_SUCCESS. On failure it will set |
michael@0 | 1224 | * an error on the error stack and return PR_FAILURE. |
michael@0 | 1225 | * |
michael@0 | 1226 | * The error may be one of the following values: |
michael@0 | 1227 | * NSS_ERROR_NO_MEMORY |
michael@0 | 1228 | * NSS_ERROR_TRACKER_NOT_INITIALIZED |
michael@0 | 1229 | * NSS_ERROR_DUPLICATE_POINTER |
michael@0 | 1230 | * |
michael@0 | 1231 | * Return value: |
michael@0 | 1232 | * PR_SUCCESS |
michael@0 | 1233 | * PR_FAILURE |
michael@0 | 1234 | */ |
michael@0 | 1235 | |
michael@0 | 1236 | #ifdef DEBUG |
michael@0 | 1237 | NSS_EXTERN PRStatus |
michael@0 | 1238 | nssPointerTracker_add |
michael@0 | 1239 | ( |
michael@0 | 1240 | nssPointerTracker *tracker, |
michael@0 | 1241 | const void *pointer |
michael@0 | 1242 | ); |
michael@0 | 1243 | |
michael@0 | 1244 | extern const NSSError NSS_ERROR_NO_MEMORY; |
michael@0 | 1245 | extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED; |
michael@0 | 1246 | extern const NSSError NSS_ERROR_DUPLICATE_POINTER; |
michael@0 | 1247 | #endif /* DEBUG */ |
michael@0 | 1248 | |
michael@0 | 1249 | /* |
michael@0 | 1250 | * nssPointerTracker_remove |
michael@0 | 1251 | * |
michael@0 | 1252 | * This method is only present in debug builds. |
michael@0 | 1253 | * |
michael@0 | 1254 | * This routine removes the specified pointer from the |
michael@0 | 1255 | * nssPointerTracker object. It does not call any destructor for the |
michael@0 | 1256 | * object; rather, this should be called from the object's destructor. |
michael@0 | 1257 | * The nssPointerTracker is threadsafe, but this call is not |
michael@0 | 1258 | * idempotent. This routine returns a PRStatus value; if successful |
michael@0 | 1259 | * it will return PR_SUCCESS. On failure it will set an error on the |
michael@0 | 1260 | * error stack and return PR_FAILURE. |
michael@0 | 1261 | * |
michael@0 | 1262 | * The error may be one of the following values: |
michael@0 | 1263 | * NSS_ERROR_TRACKER_NOT_INITIALIZED |
michael@0 | 1264 | * NSS_ERROR_POINTER_NOT_REGISTERED |
michael@0 | 1265 | * |
michael@0 | 1266 | * Return value: |
michael@0 | 1267 | * PR_SUCCESS |
michael@0 | 1268 | * PR_FAILURE |
michael@0 | 1269 | */ |
michael@0 | 1270 | |
michael@0 | 1271 | #ifdef DEBUG |
michael@0 | 1272 | NSS_EXTERN PRStatus |
michael@0 | 1273 | nssPointerTracker_remove |
michael@0 | 1274 | ( |
michael@0 | 1275 | nssPointerTracker *tracker, |
michael@0 | 1276 | const void *pointer |
michael@0 | 1277 | ); |
michael@0 | 1278 | |
michael@0 | 1279 | extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED; |
michael@0 | 1280 | extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED; |
michael@0 | 1281 | #endif /* DEBUG */ |
michael@0 | 1282 | |
michael@0 | 1283 | /* |
michael@0 | 1284 | * nssPointerTracker_verify |
michael@0 | 1285 | * |
michael@0 | 1286 | * This method is only present in debug builds. |
michael@0 | 1287 | * |
michael@0 | 1288 | * This routine verifies that the specified pointer has been registered |
michael@0 | 1289 | * with the nssPointerTracker object. The nssPointerTracker object is |
michael@0 | 1290 | * threadsafe, and this call may be safely called from multiple threads |
michael@0 | 1291 | * simultaneously with the same arguments. This routine returns a |
michael@0 | 1292 | * PRStatus value; if the pointer is registered this will return |
michael@0 | 1293 | * PR_SUCCESS. Otherwise it will set an error on the error stack and |
michael@0 | 1294 | * return PR_FAILURE. Although the error is suitable for leaving on |
michael@0 | 1295 | * the stack, callers may wish to augment the information available by |
michael@0 | 1296 | * placing a more type-specific error on the stack. |
michael@0 | 1297 | * |
michael@0 | 1298 | * The error may be one of the following values: |
michael@0 | 1299 | * NSS_ERROR_POINTER_NOT_REGISTERED |
michael@0 | 1300 | * |
michael@0 | 1301 | * Return value: |
michael@0 | 1302 | * PR_SUCCESS |
michael@0 | 1303 | * PR_FAILRUE |
michael@0 | 1304 | */ |
michael@0 | 1305 | |
michael@0 | 1306 | #ifdef DEBUG |
michael@0 | 1307 | NSS_EXTERN PRStatus |
michael@0 | 1308 | nssPointerTracker_verify |
michael@0 | 1309 | ( |
michael@0 | 1310 | nssPointerTracker *tracker, |
michael@0 | 1311 | const void *pointer |
michael@0 | 1312 | ); |
michael@0 | 1313 | |
michael@0 | 1314 | extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED; |
michael@0 | 1315 | #endif /* DEBUG */ |
michael@0 | 1316 | |
michael@0 | 1317 | /* |
michael@0 | 1318 | * libc |
michael@0 | 1319 | * |
michael@0 | 1320 | * nsslibc_memcpy |
michael@0 | 1321 | * nsslibc_memset |
michael@0 | 1322 | * nsslibc_offsetof |
michael@0 | 1323 | */ |
michael@0 | 1324 | |
michael@0 | 1325 | /* |
michael@0 | 1326 | * nsslibc_memcpy |
michael@0 | 1327 | * |
michael@0 | 1328 | * Errors: |
michael@0 | 1329 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 1330 | * |
michael@0 | 1331 | * Return value: |
michael@0 | 1332 | * NULL on error |
michael@0 | 1333 | * The destination pointer on success |
michael@0 | 1334 | */ |
michael@0 | 1335 | |
michael@0 | 1336 | NSS_EXTERN void * |
michael@0 | 1337 | nsslibc_memcpy |
michael@0 | 1338 | ( |
michael@0 | 1339 | void *dest, |
michael@0 | 1340 | const void *source, |
michael@0 | 1341 | PRUint32 n |
michael@0 | 1342 | ); |
michael@0 | 1343 | |
michael@0 | 1344 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 1345 | |
michael@0 | 1346 | /* |
michael@0 | 1347 | * nsslibc_memset |
michael@0 | 1348 | * |
michael@0 | 1349 | * Errors: |
michael@0 | 1350 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 1351 | * |
michael@0 | 1352 | * Return value: |
michael@0 | 1353 | * NULL on error |
michael@0 | 1354 | * The destination pointer on success |
michael@0 | 1355 | */ |
michael@0 | 1356 | |
michael@0 | 1357 | NSS_EXTERN void * |
michael@0 | 1358 | nsslibc_memset |
michael@0 | 1359 | ( |
michael@0 | 1360 | void *dest, |
michael@0 | 1361 | PRUint8 byte, |
michael@0 | 1362 | PRUint32 n |
michael@0 | 1363 | ); |
michael@0 | 1364 | |
michael@0 | 1365 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 1366 | |
michael@0 | 1367 | /* |
michael@0 | 1368 | * nsslibc_memequal |
michael@0 | 1369 | * |
michael@0 | 1370 | * Errors: |
michael@0 | 1371 | * NSS_ERROR_INVALID_POINTER |
michael@0 | 1372 | * |
michael@0 | 1373 | * Return value: |
michael@0 | 1374 | * PR_TRUE if they match |
michael@0 | 1375 | * PR_FALSE if they don't |
michael@0 | 1376 | * PR_FALSE upon error |
michael@0 | 1377 | */ |
michael@0 | 1378 | |
michael@0 | 1379 | NSS_EXTERN PRBool |
michael@0 | 1380 | nsslibc_memequal |
michael@0 | 1381 | ( |
michael@0 | 1382 | const void *a, |
michael@0 | 1383 | const void *b, |
michael@0 | 1384 | PRUint32 len, |
michael@0 | 1385 | PRStatus *statusOpt |
michael@0 | 1386 | ); |
michael@0 | 1387 | |
michael@0 | 1388 | extern const NSSError NSS_ERROR_INVALID_POINTER; |
michael@0 | 1389 | |
michael@0 | 1390 | #define nsslibc_offsetof(str, memb) ((PRPtrdiff)(&(((str *)0)->memb))) |
michael@0 | 1391 | |
michael@0 | 1392 | PR_END_EXTERN_C |
michael@0 | 1393 | |
michael@0 | 1394 | #endif /* BASE_H */ |