From aebb99bf39331e4518e93f03343fbdd0329e2f3a Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@kth.se>
Date: Thu, 12 Sep 2024 18:48:55 +0200
Subject: Add libhashsum_get_relative_performance.3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <maandree@kth.se>
---
 libhashsum.7                          |  3 +-
 libhashsum.h                          |  2 +-
 libhashsum_get_relative_performance.3 | 57 +++++++++++++++++++++++++++++++++++
 libhashsum_init_hasher_from_string.3  |  3 +-
 4 files changed, 62 insertions(+), 3 deletions(-)
 create mode 100644 libhashsum_get_relative_performance.3

diff --git a/libhashsum.7 b/libhashsum.7
index ec8dcb1..6bdf984 100644
--- a/libhashsum.7
+++ b/libhashsum.7
@@ -62,4 +62,5 @@ function that can select the appropriate initialiser
 based on an enum value that specifies the algorithm.
 .SH SEE ALSO
 .BR libhashsum_init_hasher (3),
-.BR libhashsum_init_hasher_from_string (3)
+.BR libhashsum_init_hasher_from_string (3),
+.BR libhashsum_get_relative_performance (3)
diff --git a/libhashsum.h b/libhashsum.h
index 01d8fbd..6abc02e 100644
--- a/libhashsum.h
+++ b/libhashsum.h
@@ -700,7 +700,7 @@ int libhashsum_init_hasher_from_string(struct libhashsum_hasher *this, const cha
  * @since  1.1
  */
 LIBHASHSUM_NONNULL_ LIBHASHSUM_PURE_
-uint64_t libhashsum_get_relative_performance(struct libhashsum_hasher *this);
+uint64_t libhashsum_get_relative_performance(struct libhashsum_hasher *this); /* TODO man, test */
 
 /**
  * Create an initialised state for MD2
diff --git a/libhashsum_get_relative_performance.3 b/libhashsum_get_relative_performance.3
new file mode 100644
index 0000000..86e9278
--- /dev/null
+++ b/libhashsum_get_relative_performance.3
@@ -0,0 +1,57 @@
+.TH LIBHASHSUM_GET_RELATIVE_PERFORMANCE 3 libhashsum
+.SH NAME
+libhashsum_get_relative_performance - get performance of hash function
+
+.SH SYNOPSIS
+.nf
+#include <libhashsum.h>
+
+uint64_t \fBlibhashsum_get_relative_performance\fP(struct libhashsum_hasher *\fIhasher\fP);
+.fi
+.PP
+Link with
+.IR -lhashsum .
+
+.SH DESCRIPTION
+The
+.B libhashsum_get_relative_performance
+function returns an estimate, approximate
+performance relative to some unspecified
+reference pointer, where a higher value
+indicates higher throughput, for the hash
+function, and hash function configurations,
+.I hasher
+has been initialised for.
+.PP
+.I hasher
+must not be
+.IR NULL .
+
+.SH RETURN VALUE
+Upon successful completion, the
+.B libhashsum_get_relative_performance
+function returns value indicating the
+performance of the hash function, where
+a higher value means higher performance.
+The function returns 0 if no estimate
+is available.
+
+.SH ERRORS
+The
+.B libhashsum_get_relative_performance
+function cannot fail.
+
+.SH HISTORY
+Introduced in libhashsum 1.1.
+
+.SH NOTES
+The performance may differ between CPUs,
+especially between architectures. Currently
+all measurements are created on x86-64 and
+some functions use special optimisations
+that may not be available which would
+drastically change the performance.
+
+.SH SEE ALSO
+.BR libhashsum (7),
+.BR libhashsum_init_hasher_from_string (3)
diff --git a/libhashsum_init_hasher_from_string.3 b/libhashsum_init_hasher_from_string.3
index d8fffb4..1f1da6f 100644
--- a/libhashsum_init_hasher_from_string.3
+++ b/libhashsum_init_hasher_from_string.3
@@ -402,4 +402,5 @@ field was added in libhashsum 1.1.
 .SH SEE ALSO
 .BR libhashsum (7),
 .BR libhashsum_init_hasher (3),
-.BR libhashsum_get_algorithm_from_string (3)
+.BR libhashsum_get_algorithm_from_string (3),
+.BR libhashsum_get_relative_performance (3)
-- 
cgit v1.2.3-70-g09d2