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