Latest update

doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod

@@ -0,0 +1,120 @@
+=pod
+
+=head1 NAME
+
+DEFINE_SPARSE_ARRAY_OF, ossl_sa_TYPE_new, ossl_sa_TYPE_free,
+ossl_sa_TYPE_free_leaves, ossl_sa_TYPE_num, ossl_sa_TYPE_doall,
+ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
+- sparse array container
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+ #include "internal/sparse_array.h"
+
+ typedef struct sparse_array_st OPENSSL_SA;
+
+ SPARSE_ARRAY_OF(TYPE)
+ DEFINE_SPARSE_ARRAY_OF(TYPE)
+
+ SPARSE_ARRAY_OF(TYPE) *ossl_sa_TYPE_new(void);
+ void ossl_sa_TYPE_free(const SPARSE_ARRAY_OF(TYPE) *sa);
+ void ossl_sa_TYPE_free_leaves(const SPARSE_ARRAY_OF(TYPE) *sa);
+ int ossl_sa_TYPE_num(const SPARSE_ARRAY_OF(TYPE) *sa);
+ void ossl_sa_TYPE_doall(const OPENSSL_SA *sa, void (*leaf)(size_t, void *));
+ void ossl_sa_TYPE_doall_arg(const OPENSSL_SA *sa,
+                             void (*leaf)(size_t, void *, void *), void *arg);
+ TYPE *ossl_sa_TYPE_get(const SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
+ int ossl_sa_TYPE_set(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx, TYPE *value);
+
+=head1 DESCRIPTION
+
+SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
+B<TYPE>.  DEFINE_STACK_OF() creates set of functions for a sparse array of
+B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each
+element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and
+each function name begins with I<ossl_sa_TYPE_>. For example:
+
+ TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
+
+ossl_sa_TYPE_num() returns the number of elements in B<sa> or 0 if B<sa> is
+B<NULL>.
+
+ossl_sa_TYPE_get() returns element B<idx> in B<sa>, where B<idx> starts at
+zero. If B<idx> refers to a value that has not been set then B<NULL> is
+returned.
+
+ossl_sa_TYPE_set() sets element B<idx> in B<sa> to B<value>, where B<idx>
+starts at zero. The sparse array will be resized as required.
+
+ossl_sa_TYPE_new() allocates a new empty sparse array.
+
+ossl_sa_TYPE_free() frees up the B<sa> structure. It does B<not> free up any
+elements of B<sa>. After this call B<sa> is no longer valid.
+
+ossl_sa_TYPE_free_leaves() frees up the B<sa> structure and all of its
+elements.  After this call B<sa> is no longer valid.
+
+ossl_sa_TYPE_doall() calls the function B<leaf> for each element in B<sa>
+in ascending index order. The index position, within the sparse array,
+of each item is passed as the first argument to the leaf function and a
+pointer to the associated value is is passed as the second argument.
+
+ossl_sa_TYPE_doall_arg() calls the function B<leaf> for each element in
+B<sa> in ascending index order. The index position, within the sparse
+array, of each item is passed as the first argument to the leaf function,
+a pointer to the associated value is passed as the second argument and
+the third argument is the user supplied B<arg>.
+
+
+=head1 NOTES
+
+Sparse arrays are an internal data structure and should B<not> be used by user
+applications.
+
+Care should be taken when accessing sparse arrays in multi-threaded
+environments.  The ossl_sa_TYPE_set operation can cause the internal structure
+of the sparse array to change which causes race conditions if the sparse array
+is accessed in a different thread.
+
+SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
+
+The underlying utility B<OPENSSL_SA_> API should not be used directly.  It
+defines these functions: OPENSSL_SA_doall, OPENSSL_SA_doall_arg,
+OPENSSL_SA_free, OPENSSL_SA_free_leaves, OPENSSL_SA_get, OPENSSL_SA_new,
+OPENSSL_SA_num and OPENSSL_SA_set.
+
+=head1 RETURN VALUES
+
+ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0>
+if the passed sparse array is B<NULL>.
+
+ossl_sa_TYPE_get() returns a pointer to a sparse array element or B<NULL> if
+the element has not be set.
+
+ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter
+case, the elements of the sparse array remain unchanged, although the internal
+structures might have.
+
+ossl_sa_TYPE_new() returns an empty sparse array or B<NULL> if an error
+occurs.
+
+ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and
+ossl_sa_TYPE_free_leaves() do not return values.
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
+(c) 2019, Oracle and/or its affiliates.  All rights reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use this
+file except in compliance with the License.  You can obtain a copy in the file
+LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut