https://www.liblfds.org/mediawiki/index.php?title=r7.1.0:Usage_Guide_(libbenchmark)&feed=atom&action=historyr7.1.0:Usage Guide (libbenchmark) - Revision history2024-03-29T06:08:23ZRevision history for this page on the wikiMediaWiki 1.36.0https://www.liblfds.org/mediawiki/index.php?title=r7.1.0:Usage_Guide_(libbenchmark)&diff=847&oldid=prevAdmin at 04:28, 27 May 20162016-05-27T04:28:38Z<p></p>
<p><b>New page</b></p><div>{{DISPLAYTITLE:Usage Guide (libbenchmark)}}<br />
==Introduction==<br />
This page describes how to use the ''libbenchmark'' library.<br />
<br />
The library implements a great deal of functionality, almost all of which is used and only used by the ''libbenchmark'' library itself. From the point of view of an external caller to its API, there are only a few functions; a couple to init and run the entire benchmark suite, a few more to handle the results from a benchmark run and one or two miscellanous functions.<br />
<br />
==Usage==<br />
To use ''libbenchmark'', include the header file ''libbenchmark.h'' and link as normal to the library in your build.<br />
<br />
==Dependencies==<br />
The ''libbenchmark'' libraries depends on the ''libshared'' library and the ''liblfds710'' library.<br />
<br />
==Source Files==<br />
└── test_and_benchmark<br />
└── libbenchmark<br />
├── inc<br />
│ └── libbenchmark<br />
│ ├── libbenchmark_benchmarksuite.h<br />
│ ├── libbenchmark_enums.h<br />
│ ├── libbenchmark_gnuplot.h<br />
│ ├── libbenchmark_results.h<br />
│ ├── libbenchmark_topology.h<br />
│ └── libbenchmark_topology_node.h<br />
└── src<br />
├── libbenchmark_benchmarksuite<br />
│ ├── libbenchmark_benchmarksuite_cleanup.c<br />
│ ├── libbenchmark_benchmarksuite_gnuplot.c<br />
│ ├── libbenchmark_benchmarksuite_init.c<br />
│ ├── libbenchmark_benchmarksuite_internal.h<br />
│ └── libbenchmark_benchmarksuite_run.c<br />
├── libbenchmark_results<br />
│ ├── libbenchmark_results_cleanup.c<br />
│ ├── libbenchmark_results_get_result.c<br />
│ ├── libbenchmark_results_init.c<br />
│ └── libbenchmark_results_internal.h<br />
├── libbenchmark_topology<br />
│ ├── libbenchmark_topology_cleanup.c<br />
│ ├── libbenchmark_topology_init.c<br />
│ ├── libbenchmark_topology_internal.h<br />
│ ├── libbenchmark_topology_numa.c<br />
│ └── libbenchmark_topology_lpsets.c<br />
└── libbenchmark_topology_node<br />
├── libbenchmark_topology_node_cleanup.c<br />
└── libbenchmark_topology_node_init.c<br />
<br />
This is a small subset of the full set of files, and shows only those files used by the publically exposed APIs.<br />
<br />
==Defines==<br />
#define [[r7.1.0:define LIBBENCHMARK_BENCHMARKSUITE_OPTION_DURATION|LIBBENCHMARK_BENCHMARKSUITE_OPTION_DURATION]]<br />
<br />
==Enums==<br />
enum [[r7.1.0:enum libbenchmark_benchmark_id|libbenchmark_benchmark_id]];<br />
enum [[r7.1.0:enum libbenchmark_datastructure_id|libbenchmark_datastructure_id]];<br />
enum [[r7.1.0:enum libbenchmark_lock_id|libbenchmark_lock_id]];<br />
enum [[r7.1.0:enum libbenchmark_topology_node_type|libbenchmark_topology_node_type]];<br />
enum [[r7.1.0:enum libbenchmark_topology_numa_mode|libbenchmark_topology_numa_mode]];<br />
<br />
==Opaque Structures==<br />
struct [[r7.1.0:struct lfds710_list_aso_element|lfds710_list_aso_element]];<br />
struct [[r7.1.0:struct lfds710_list_aso_state|lfds710_list_aso_state]];<br />
struct [[r7.1.0:struct lfds710_list_asu_state|lfds710_list_asu_state]];<br />
struct [[r7.1.0:struct libbenchmark_gnuplot_options|libbenchmark_gnuplot_options]];<br />
struct [[r7.1.0:struct libbenchmark_results_state|libbenchmark_results_state]];<br />
struct [[r7.1.0:struct libbenchmark_benchmarksuite_state|libbenchmark_benchmarksuite_state]];<br />
struct [[r7.1.0:struct libbenchmark_topology_state|libbenchmark_topology_state]];<br />
struct [[r7.1.0:struct libbenchmark_topology_node_state|libbenchmark_topology_node_state]];<br />
struct [[r7.1.0:struct libshared_memory_state|libshared_memory_state]];<br />
<br />
==Macros==<br />
#define [[r7.1.0:macro LIBBENCHMARK_TOPOLOGY_NODE_SET_TYPE|LIBBENCHMARK_TOPOLOGY_NODE_SET_TYPE]]( tns, node_type )<br />
#define [[r7.1.0:macro LIBBENCHMARK_TOPOLOGY_NODE_SET_LOGICAL_PROCESSOR_NUMBER|LIBBENCHMARK_TOPOLOGY_NODE_SET_LOGICAL_PROCESSOR_NUMBER]]( tns, processor_number )<br />
#define [[r7.1.0:macro LIBBENCHMARK_TOPOLOGY_NODE_SET_WINDOWS_GROUP_NUMBER|LIBBENCHMARK_TOPOLOGY_NODE_SET_WINDOWS_GROUP_NUMBER]]( tns, win_group_number )<br />
#define [[r7.1.0:macro LIBBENCHMARK_TOPOLOGY_NODE_UNSET_WINDOWS_GROUP_NUMBER|LIBBENCHMARK_TOPOLOGY_NODE_UNSET_WINDOWS_GROUP_NUMBER]]( tns )<br />
<br />
#define [[r7.1.0:macro LIBBENCHMARK_GNUPLOT_OPTIONS_INIT|LIBBENCHMARK_GNUPLOT_OPTIONS_INIT]]( gpo )<br />
#define [[r7.1.0:macro LIBBENCHMARK_GNUPLOT_OPTIONS_SET_Y_AXIS_SCALE_TYPE_LOGARITHMIC|LIBBENCHMARK_GNUPLOT_OPTIONS_SET_Y_AXIS_SCALE_TYPE_LOGARITHMIC]]( gpo )<br />
#define [[r7.1.0:macro LIBBENCHMARK_GNUPLOT_OPTIONS_SET_WIDTH_IN_PIXELS|LIBBENCHMARK_GNUPLOT_OPTIONS_SET_WIDTH_IN_PIXELS]]( gpo, wip )<br />
#define [[r7.1.0:macro LIBBENCHMARK_GNUPLOT_OPTIONS_SET_HEIGHT_IN_PIXELS|LIBBENCHMARK_GNUPLOT_OPTIONS_SET_HEIGHT_IN_PIXELS]]( gpo, wip )<br />
<br />
==Prototypes==<br />
int [[r7.1.0:function libbenchmark_topology_init|libbenchmark_topology_init]]( struct libbenchmark_topology_state *ts,<br />
struct libshared_memory_state *ms );<br />
void [[r7.1.0:function libbenchmark_topology_cleanup|libbenchmark_topology_cleanup]]( struct libbenchmark_topology_state *ts );<br />
<br />
void [[r7.1.0:function libbenchmark_topology_generate_deduplicated_logical_processor_sets|libbenchmark_topology_generate_deduplicated_logical_processor_sets]]( struct libbenchmark_topology_state *ts,<br />
struct libshared_memory_state *ms,<br />
struct lfds710_list_asu_state *lp_sets );<br />
void [[r7.1.0:function libbenchmark_topology_generate_numa_modes_list|libbenchmark_topology_generate_numa_modes_list]]( struct libbenchmark_topology_state *ts,<br />
enum libbenchmark_topology_numa_mode numa_mode,<br />
struct libshared_memory_state *ms,<br />
struct lfds710_list_asu_state *numa_modes_list );<br />
<br />
void [[r7.1.0:function libbenchmark_topology_node_init|libbenchmark_topology_node_init]]( struct libbenchmark_topology_node_state *tns );<br />
void [[r7.1.0:function libbenchmark_topology_node_cleanup|libbenchmark_topology_node_cleanup]]( struct libbenchmark_topology_node_state *tns,<br />
void (*element_cleanup_callback)(struct lfds710_list_aso_state *lasos,<br />
struct lfds710_list_aso_element *lasoe) );<br />
<br />
void [[r7.1.0:function libbenchmark_results_init|libbenchmark_results_init]]( struct libbenchmark_results_state *rs,<br />
struct libshared_memory_state *ms );<br />
void [[r7.1.0:function libbenchmark_results_cleanup|libbenchmark_results_cleanup]]( struct libbenchmark_results_state *rs );<br />
int [[r7.1.0:function libbenchmark_results_get_result|libbenchmark_results_get_result]]( struct libbenchmark_results_state *rs,<br />
enum libbenchmark_datastructure_id datastructure_id,<br />
enum libbenchmark_benchmark_id benchmark_id,<br />
enum libbenchmark_lock_id lock_id,<br />
enum libbenchmark_topology_numa_mode numa_mode,<br />
struct lfds710_list_aso_state *lpset,<br />
struct libbenchmark_topology_node_state *tns,<br />
lfds710_pal_uint_t *result );<br />
<br />
void [[r7.1.0:function libbenchmark_benchmarksuite_init|libbenchmark_benchmarksuite_init]]( struct libbenchmark_benchmarksuite_state *bss,<br />
struct libbenchmark_topology_state *ts,<br />
struct libshared_memory_state *ms,<br />
enum libbenchmark_topology_numa_mode numa_mode,<br />
lfds710_pal_uint_t options_bitmask,<br />
lfds710_pal_uint_t benchmark_duration_in_seconds );<br />
void [[r7.1.0:function libbenchmark_benchmarksuite_cleanup|libbenchmark_benchmarksuite_cleanup]]( struct libbenchmark_benchmarksuite_state *bss );<br />
void [[r7.1.0:function libbenchmark_benchmarksuite_run|libbenchmark_benchmarksuite_run]]( struct libbenchmark_benchmarksuite_state *bss,<br />
struct libbenchmark_results_state *rs );<br />
void [[r7.1.0:function libbenchmark_benchmarksuite_get_list_of_gnuplot_strings|libbenchmark_benchmarksuite_get_list_of_gnuplot_strings]]( struct libbenchmark_benchmarksuite_state *bss,<br />
struct libbenchmark_results_state *rs,<br />
char *gnuplot_system_string,<br />
struct libbenchmark_gnuplot_options *gpo,<br />
struct lfds710_list_asu_state *list_of_gnuplot_strings );<br />
<br />
==Overview==<br />
It has become apparent from creating this page that the API interface to benchmarking is too complicated. The API to run the benchmarks and get hold of the results is actually simple enough - two init functions (one for the benchmark and one for the results) and then a function to run the benchmarks. The problem come when offering APIs to query the results.<br />
<br />
There are many data structures, each of which can have many benchmarks, where each benchmark is run both for the ''liblfds'' lock-free version and then for the full range of system provided locking mechanisms, where each run of the benchmark for a given lock type runs over many combinations of logical cores, where for every combination a result is stored for each logical processor; and all of this on a NUMA system with more than one NUMA node is run twice, once NUMA aware and once not, to show how much difference this makes to performance.<br />
<br />
As such, values for all of these parameters must be specified to the function which queries the result state - and this exposes a great deal of complexity and functionality, as can be seen above.<br />
<br />
It will take a day to document this library, and the effort to do so is futile, because it will still be too complex to use. As such, the effort will go instead into simplifying the API. However, this should not delay the release of 7.1.0, so the functions in this library will for now go undocumented.<br />
<br />
==See Also==<br />
* [[r7.1.0:Usage Guide (benchmarking)|Usage Guide (benchmarking)]]</div>Admin