From: Hugo Landau <hlandau@openssl.org>
Date: Mon, 11 Dec 2023 07:57:54 +0000 (+0000)
Subject: LHASH: Document down_load functions
X-Git-Tag: openssl-3.1.5~82
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b51644997862e08dc3dad158c8a916524e2000bf;p=thirdparty%2Fopenssl.git

LHASH: Document down_load functions

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23032)

(cherry picked from commit f8c75e053569cdcbf0d39620e28b4044f1be04f1)
---

diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod
index 06408e0dd67..1ec2aa4b534 100644
--- a/doc/man3/OPENSSL_LH_COMPFUNC.pod
+++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod
@@ -8,10 +8,12 @@ LHASH_DOALL_ARG_FN_TYPE,
 IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN,
 lh_TYPE_new, lh_TYPE_free, lh_TYPE_flush,
 lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve,
-lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error,
+lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_num_items, lh_TYPE_get_down_load,
+lh_TYPE_set_down_load, lh_TYPE_error,
 OPENSSL_LH_new, OPENSSL_LH_free,  OPENSSL_LH_flush,
 OPENSSL_LH_insert, OPENSSL_LH_delete, OPENSSL_LH_retrieve,
-OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_error
+OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_num_items,
+OPENSSL_LH_get_down_load, OPENSSL_LH_set_down_load, OPENSSL_LH_error
 - dynamic hash table
 
 =head1 SYNOPSIS
@@ -36,6 +38,10 @@ OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_error
  void lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func,
                         TYPE *arg);
 
+ unsigned long lh_TYPE_num_items(OPENSSL_LHASH *lh);
+ unsigned long lh_TYPE_get_down_load(OPENSSL_LHASH *lh);
+ void lh_TYPE_set_down_load(OPENSSL_LHASH *lh, unsigned long dl);
+
  int lh_TYPE_error(LHASH_OF(TYPE) *table);
 
  typedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *);
@@ -54,8 +60,14 @@ OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_error
  void OPENSSL_LH_doall(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNC func);
  void OPENSSL_LH_doall_arg(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNCARG func, void *arg);
 
+ unsigned long OPENSSL_LH_num_items(OPENSSL_LHASH *lh);
+ unsigned long OPENSSL_LH_get_down_load(OPENSSL_LHASH *lh);
+ void OPENSSL_LH_set_down_load(OPENSSL_LHASH *lh, unsigned long dl);
+
  int OPENSSL_LH_error(OPENSSL_LHASH *lh);
 
+ #define LH_LOAD_MULT   /* integer constant */
+
 The following macro is deprecated:
 
  DEFINE_LHASH_OF(TYPE);
@@ -199,17 +211,26 @@ B<lh_I<TYPE>_doall>() or B<lh_I<TYPE>_doall_arg>().
 B<lh_I<TYPE>_error>() can be used to determine if an error occurred in the last
 operation.
 
+B<lh_I<TYPE>_num_items>() returns the number of items in the hash table.
+
+B<lh_I<TYPE>_get_down_load>() and B<lh_I<TYPE>_set_down_load>() get and set the
+factor used to determine when the hash table is contracted. The factor is the
+load factor at or below which hash table contraction will occur, multiplied by
+B<LH_LOAD_MULT>, where the load factor is the number of items divided by the
+number of nodes. Setting this value to 0 disables hash table contraction.
+
 OPENSSL_LH_new() is the same as the B<lh_I<TYPE>_new>() except that it is not
 type specific. So instead of returning an B<LHASH_OF(I<TYPE>)> value it returns
 a B<void *>. In the same way the functions OPENSSL_LH_free(),
 OPENSSL_LH_flush(), OPENSSL_LH_insert(), OPENSSL_LH_delete(),
-OPENSSL_LH_retrieve(), OPENSSL_LH_doall(), OPENSSL_LH_doall_arg(), and
-OPENSSL_LH_error() are equivalent to the similarly named B<lh_I<TYPE>> functions
-except that they return or use a B<void *> where the equivalent B<lh_I<TYPE>>
-function returns or uses a B<I<TYPE> *> or B<LHASH_OF(I<TYPE>) *>. B<lh_I<TYPE>>
-functions are implemented as type checked wrappers around the B<OPENSSL_LH>
-functions. Most applications should not call the B<OPENSSL_LH> functions
-directly.
+OPENSSL_LH_retrieve(), OPENSSL_LH_doall(), OPENSSL_LH_doall_arg(),
+OPENSSL_LH_num_items(), OPENSSL_LH_get_down_load(), OPENSSL_LH_set_down_load()
+and OPENSSL_LH_error() are equivalent to the similarly named B<lh_I<TYPE>>
+functions except that they return or use a B<void *> where the equivalent
+B<lh_I<TYPE>> function returns or uses a B<I<TYPE> *> or B<LHASH_OF(I<TYPE>) *>.
+B<lh_I<TYPE>> functions are implemented as type checked wrappers around the
+B<OPENSSL_LH> functions. Most applications should not call the B<OPENSSL_LH>
+functions directly.
 
 =head1 RETURN VALUES
 
diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index 27c8018c24d..ab60764a4f2 100644
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -763,9 +763,6 @@ OCSP_response_status_str(3)
 OCSP_url_svcloc_new(3)
 OPENSSL_DIR_end(3)
 OPENSSL_DIR_read(3)
-OPENSSL_LH_get_down_load(3)
-OPENSSL_LH_num_items(3)
-OPENSSL_LH_set_down_load(3)
 OPENSSL_LH_strhash(3)
 OPENSSL_asc2uni(3)
 OPENSSL_die(3)