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