doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 DEFINE_SPARSE_ARRAY_OF, ossl_sa_TYPE_new, ossl_sa_TYPE_free,
   6 ossl_sa_TYPE_free_leaves, ossl_sa_TYPE_num, ossl_sa_TYPE_doall,
   7 ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
   8 - sparse array container
   9
  10 =head1 SYNOPSIS
  11
  12 =for openssl generic
  13
  14  #include "crypto/sparse_array.h"
  15
  16  typedef struct sparse_array_st OPENSSL_SA;
  17
  18  SPARSE_ARRAY_OF(TYPE)
  19  DEFINE_SPARSE_ARRAY_OF(TYPE)
  20
  21  SPARSE_ARRAY_OF(TYPE) *ossl_sa_TYPE_new(void);
  22  void ossl_sa_TYPE_free(const SPARSE_ARRAY_OF(TYPE) *sa);
  23  void ossl_sa_TYPE_free_leaves(const SPARSE_ARRAY_OF(TYPE) *sa);
  24  size_t ossl_sa_TYPE_num(const SPARSE_ARRAY_OF(TYPE) *sa);
  25  void ossl_sa_TYPE_doall(const OPENSSL_SA *sa, void (*leaf)(ossl_uintmax_t,
  26                                                             void *));
  27  void ossl_sa_TYPE_doall_arg(const OPENSSL_SA *sa,
  28                              void (*leaf)(ossl_uintmax_t, void *, void *),
  29                              void *arg);
  30  TYPE *ossl_sa_TYPE_get(const SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx);
  31  int ossl_sa_TYPE_set(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx,
  32                       TYPE *value);
  33
  34 =head1 DESCRIPTION
  35
  36 =begin comment
  37
  38 POD is pretty good at recognising function names and making them appropriately
  39 bold...  however, when part of the function name is variable, we have to help
  40 the processor along
  41
  42 =end comment
  43
  44 SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
  45 B<I<TYPE>>.  DEFINE_STACK_OF() creates set of functions for a sparse
  46 array of B<I<TYPE>>. This will mean that a pointer to type B<I<TYPE>>
  47 is stored in each element of a sparse array, the type is referenced by
  48 B<SPARSE_ARRAY_OF>(B<I<TYPE>>) and each function name begins with
  49 B<ossl_sa_I<TYPE>_>. For example:
  50
  51  TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx);
  52
  53 B<ossl_sa_I<TYPE>_num>() returns the number of elements in I<sa> or 0 if I<sa>
  54 is NULL.
  55
  56 B<ossl_sa_I<TYPE>_get>() returns element I<idx> in I<sa>, where I<idx> starts
  57 at zero. If I<idx> refers to a value that has not been set then NULL is
  58 returned.
  59
  60 B<ossl_sa_I<TYPE>_set>() sets element I<idx> in I<sa> to I<value>, where I<idx>
  61 starts at zero. The sparse array will be resized as required.
  62
  63 B<ossl_sa_I<TYPE>_new>() allocates a new empty sparse array.
  64
  65 B<ossl_sa_I<TYPE>_free>() frees up the I<sa> structure. It does I<not> free up any
  66 elements of I<sa>. After this call I<sa> is no longer valid.
  67
  68 B<ossl_sa_I<TYPE>_free_leaves>() frees up the I<sa> structure and all of its
  69 elements.  After this call I<sa> is no longer valid.
  70
  71 B<ossl_sa_I<TYPE>_doall>() calls the function I<leaf> for each element in I<sa>
  72 in ascending index order. The index position, within the sparse array,
  73 of each item is passed as the first argument to the leaf function and a
  74 pointer to the associated value is is passed as the second argument.
  75
  76 B<ossl_sa_I<TYPE>_doall_arg>() calls the function I<leaf> for each element in
  77 I<sa> in ascending index order. The index position, within the sparse
  78 array, of each item is passed as the first argument to the leaf function,
  79 a pointer to the associated value is passed as the second argument and
  80 the third argument is the user supplied I<arg>.
  81
  82
  83 =head1 NOTES
  84
  85 Sparse arrays are an internal data structure and should B<not> be used by user
  86 applications.
  87
  88 Care should be taken when accessing sparse arrays in multi-threaded
  89 environments.  The B<ossl_sa_I<TYPE>_set>() operation can cause the internal
  90 structure of the sparse array to change which causes race conditions if the
  91 sparse array is accessed in a different thread.
  92
  93 SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
  94
  95 The underlying utility B<OPENSSL_SA_> API should not be used directly.  It
  96 defines these functions: OPENSSL_SA_doall, OPENSSL_SA_doall_arg,
  97 OPENSSL_SA_free, OPENSSL_SA_free_leaves, OPENSSL_SA_get, OPENSSL_SA_new,
  98 OPENSSL_SA_num and OPENSSL_SA_set.
  99
 100 =head1 RETURN VALUES
 101
 102 B<ossl_sa_I<TYPE>_num>() returns the number of elements in the sparse array or
 103 B<0> if the passed sparse array is NULL.
 104
 105 B<ossl_sa_I<TYPE>_get>() returns a pointer to a sparse array element or NULL if
 106 the element has not be set.
 107
 108 B<ossl_sa_I<TYPE>_set>() return B<1> on success and B<0> on error. In the latter
 109 case, the elements of the sparse array remain unchanged, although the internal
 110 structures might have.
 111
 112 B<ossl_sa_I<TYPE>_new>() returns an empty sparse array or NULL if an error
 113 occurs.
 114
 115 B<ossl_sa_I<TYPE>_doall>(), B<ossl_sa_I<TYPE>_doall_arg>(),
 116 B<ossl_sa_I<TYPE>_free>() and B<ossl_sa_I<TYPE>_free_leaves>()
 117 do not return values.
 118
 119 =head1 HISTORY
 120
 121 This functionality was added to OpenSSL 3.0.
 122
 123 =head1 COPYRIGHT
 124
 125 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
 126 (c) 2019, Oracle and/or its affiliates.  All rights reserved.
 127
 128 Licensed under the Apache License 2.0 (the "License").  You may not use this
 129 file except in compliance with the License.  You can obtain a copy in the file
 130 LICENSE in the source distribution or at
 131 L<https://www.openssl.org/source/license.html>.
 132
 133 =cut