Add sparse array data type.
[openssl.git] / 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  #include "internal/sparse_array.h"
13
14  typedef struct sparse_array_st OPENSSL_SA;
15
16  SPARSE_ARRAY_OF(TYPE)
17  DEFINE_SPARSE_ARRAY_OF(TYPE)
18
19  SPARSE_ARRAY_OF(TYPE) *ossl_sa_TYPE_new(void);
20  void ossl_sa_TYPE_free(const SPARSE_ARRAY_OF(TYPE) *sa);
21  void ossl_sa_TYPE_free_leaves(const SPARSE_ARRAY_OF(TYPE) *sa);
22  int ossl_sa_TYPE_num(const SPARSE_ARRAY_OF(TYPE) *sa);
23  void ossl_sa_TYPE_doall(const OPENSSL_SA *sa, void (*leaf)(void *));
24  void ossl_sa_TYPE_doall_arg(const OPENSSL_SA *sa, void (*leaf)(void *), void *arg);
25  TYPE *ossl_sa_TYPE_get(const SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
26  int ossl_sa_TYPE_set(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx, TYPE *value);
27
28 =head1 DESCRIPTION
29
30 SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
31 B<TYPE>.  DEFINE_STACK_OF() creates set of functions for a sparse array of
32 B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each
33 element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and
34 each function name begins with I<ossl_sa_TYPE_>. For example:
35
36  TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
37
38 ossl_sa_TYPE_num() returns the number of elements in B<sa> or 0 if B<sa> is
39 B<NULL>.
40
41 ossl_sa_TYPE_get() returns element B<idx> in B<sa>, where B<idx> starts at
42 zero. If B<idx> refers to a value that has not been set then B<NULL> is
43 returned.
44
45 ossl_sa_TYPE_set() sets element B<idx> in B<sa> to B<value>, where B<idx>
46 starts at zero. The sparse array will be resized as required.
47
48 ossl_sa_TYPE_new() allocates a new empty sparse array.
49
50 ossl_sa_TYPE_free() frees up the B<sa> structure. It does B<not> free up any
51 elements of B<sa>. After this call B<sa> is no longer valid.
52
53 ossl_sa_TYPE_free_leaves() frees up the B<sa> structure and all of its
54 elements.  After this call B<sa> is no longer valid.
55
56 ossl_sa_TYPE_doall() calls the function B<leaf> for each element in B<sa> in
57 ascending index order.
58
59 ossl_sa_TYPE_doall_arg() calls the function B<leaf> for each element in B<sa>
60 in ascending index order. The argument B<arg> is passed to each call of
61 B<leaf>.
62
63 =head1 NOTES
64
65 Sparse arrays are an internal data structure and should B<not> be used by user
66 applications.
67
68 Care should be taken when accessing sparse arrays in multi-threaded
69 environments.  The ossl_sa_TYPE_set operation can cause the internal structure
70 of the sparse array to change which causes race conditions if the sparse array
71 is accessed in a different thread.
72
73 SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
74
75 The underlying utility B<OPENSSL_SA_> API should not be used directly.  It
76 defines these functions: OPENSSL_SA_doall, OPENSSL_SA_doall_arg,
77 OPENSSL_SA_free, OPENSSL_SA_free_leaves, OPENSSL_SA_get, OPENSSL_SA_new,
78 OPENSSL_SA_num and OPENSSL_SA_set.
79
80 =head1 RETURN VALUES
81
82 ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0>
83 if the passed sparse array is B<NULL>.
84
85 ossl_sa_TYPE_get() returns a pointer to a sparse array element or B<NULL> if
86 the element has not be set.
87
88 ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter
89 case, the elements of the sparse array remain unchanged, although the internal
90 structures might have.
91
92 ossl_sa_TYPE_new() returns an empty sparse array or B<NULL> if an error
93 occurs.
94
95 ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and
96 ossl_sa_TYPE_free_leaves() do not return values.
97
98 =head1 HISTORY
99
100 This functionality was added to OpenSSL 3.0.0.
101
102 =head1 COPYRIGHT
103
104 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
105 (c) 2019, Oracle and/or its affiliates.  All rights reserved.
106
107 Licensed under the Apache License 2.0 (the "License").  You may not use this
108 file except in compliance with the License.  You can obtain a copy in the file
109 LICENSE in the source distribution or at
110 L<https://www.openssl.org/source/license.html>.
111
112 =cut