mirror of
https://github.com/openssl/openssl.git
synced 2024-12-15 06:01:37 +08:00
008b4ff92f
Iterators over the sparse array structures have gained an initial argument which indicates the index into the array of the element. This can be used, e.g., to delete or modify the associated value. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8229)
119 lines
4.4 KiB
Plaintext
119 lines
4.4 KiB
Plaintext
=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
|
|
|
|
#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
|