Add libhashsum_get_relative_performance.3

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 57 insertions, 0 deletions

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)