Difference between pages "r7.1.1:Usage Guide (libshared)" and "r7.1.1:Usage Guide (libtest)"

Latest revision as of 20:16, 17 February 2017

Introduction

This page describes how to use the libtest library.

The library implements a great deal of functionality, almost all of which is used and only used by the libtest 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 test suite, a few more to handle the results from a test run, and one or two miscellanous functions.

Usage

To use libtest, include the header file libtest.h and link as normal to the library in your build.

Dependencies

The libtest libraries depends on the libshared library and the liblfds711 library.

Source Files

└── test_and_benchmark
    └── libtest
        ├── inc
        │   └── libtest
        │       ├── libtest_misc.h
        │       ├── libtest_results.h
        │       └── libtest_testsuite.h
        └── src
            ├── libtest_misc
            │   └── libtest_misc_determine_erg.c
            ├── libtest_results
            │   ├── libtest_results_cleanup.c
            │   ├── libtest_results_get_result.c
            │   ├── libtest_results_init.c
            │   └── libtest_results_internal.h
            └── libtest_testsuite
                ├── libtest_testsuite_cleanup.c
                ├── libtest_testsuite_init.c
                ├── libtest_testsuite_internal.h
                └── libtest_testsuite_run.c

This is a small subset of the full set of files, and shows only those files used by the publically exposed APIs.

Enums

enum lfds711_misc_validity
enum libtest_misc_determine_erg_result
enum libtest_test_id

Opaque Structures

struct libtest_results_state
struct libtest_testsuite_state
struct libshared_memory_state

Prototypes

void libtest_testsuite_init( struct libtest_testsuite_state *ts,
                             struct libshared_memory_state *ms,
                             void (*callback_test_start)(char *test_name),
                             void (*callback_test_finish)(char *result) );
void libtest_testsuite_cleanup( struct libtest_testsuite_state *ts );
void libtest_testsuite_run( struct libtest_testsuite_state *ts,
                            struct libtest_results_state *rs );

void libtest_results_init( struct libtest_results_state *rs );
void libtest_results_cleanup( struct libtest_results_state *rs );
void libtest_results_get_result( struct libtest_results_state *rs,
                                 enum libtest_test_id test_id,
                                 enum lfds711_misc_validity *result );

void libtest_misc_determine_erg( struct libshared_memory_state *ms,
                                 lfds711_pal_uint_t (*count_array)[10],
                                 enum libtest_misc_determine_erg_result *der,
                                 lfds711_pal_uint_t *erg_length_in_bytes );

Overview

To run the tests, take the following steps;

Initialize a struct libshared_memory_state, with enough store (at least 4mb). The test code is not NUMA aware, so no special NUMA-aware allocations are required.
Initialize a struct libtest_results_state.
Initialize a struct libtest_testsuite, passing in the libshared_memory_state initialized earlier.
Call libtest_testsuite_run, passing in the struct libtest_testsuite_state and the struct libtest_results_state.

When libtest_testsuite_run returns, the struct libtest_results_state will be populated, and it can be queried with libtest_results_get_result.

A given initialized struct libtest_testsuite can be passed any number of times to libtest_testsuite_run. The struct libtest_results however must be initialized, or a new struct provided, between calls, as this structure only stores the results of a single test run.

@@ Line 1: / Line 1: @@
-{{DISPLAYTITLE:Usage Guide (libshared)}}
+{{DISPLAYTITLE:Usage Guide (libtest)}}
 ==Introduction==
-This page describes how to use the ''libshared'' library.
+This page describes how to use the ''libtest'' library.
-The library implements a great deal of functionality, almost all of which is used and only used by other ''liblfds'' components.  From the point of view of an external caller to its API, there is in fact only one API, which handles user-allocated memory.
+The library implements a great deal of functionality, almost all of which is used and only used by the ''libtest'' 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 test suite, a few more to handle the results from a test run, and one or two miscellanous functions.
 ==Usage==
-To use ''libshared'', include the header file ''libshared.h'' and link as normal to the library in your build.
+To use ''libtest'', include the header file ''libtest.h'' and link as normal to the library in your build.
 ==Dependencies==
-The ''libtest'' libraries depends on the ''liblfds711'' library.
+The ''libtest'' libraries depends on the ''libshared'' library and the ''liblfds711'' library.
 ==Source Files==
   └── test_and_benchmark
-      └── libshared
+      └── libtest
           ├── inc
-          │   ├── libshared
+          │   └── libtest
-          │   │   └── libshared_memory.h
+          │       ├── libtest_misc.h
-         └── src
+         │       ├── libtest_results.h
-              └── libshared_memory
+         │       └── libtest_testsuite.h
-                  ├── libshared_memory_add.c
+         └── src
-                 ├── libshared_memory_cleanup.c
+              ├── libtest_misc
-                  └── libshared_memory_init.c
+             │   └── libtest_misc_determine_erg.c
+             ├── libtest_results
+              │   ├── libtest_results_cleanup.c
+             │   ├── libtest_results_get_result.c
+             │   ├── libtest_results_init.c
+             │   └── libtest_results_internal.h
+             └── libtest_testsuite
+                 ├── libtest_testsuite_cleanup.c
+                 ├── libtest_testsuite_init.c
+                 ├── libtest_testsuite_internal.h
+                 └── libtest_testsuite_run.c
 This is a small subset of the full set of files, and shows only those files used by the publically exposed APIs.
+==Enums==
+ enum [[r7.1.1:enum lfds711_misc_validity|lfds711_misc_validity]]
+ enum [[r7.1.1:enum libtest_misc_determine_erg_result|libtest_misc_determine_erg_result]]
+ enum [[r7.1.1:enum libtest_test_id|libtest_test_id]]
 ==Opaque Structures==
-  struct [[r7.1.1:struct libshared_memory_state|libshared_memory_state]];
+ struct [[r7.1.1:struct libtest_results_state|libtest_results_state]]
+ struct [[r7.1.1:struct libtest_testsuite_state|libtest_testsuite_state]]
+  struct [[r7.1.1:struct libshared_memory_state|libshared_memory_state]]
 ==Prototypes==
-  void [[r7.1.1:function libshared_memory_init|libshared_memory_init]]( struct libshared_memory_state *ms );
+  void [[r7.1.1:function libtest_testsuite_init|libtest_testsuite_init]]( struct libtest_testsuite_state *ts,
-  void [[r7.1.1:function libshared_memory_cleanup|libshared_memory_cleanup]]( struct libshared_memory_state *ms,
+                              struct libshared_memory_state *ms,
-                                void (*memory_cleanup_callback)(enum flag known_numa_node_flag,
+                              void (*callback_test_start)(char *test_name),
-                                                                void *store,
+                              void (*callback_test_finish)(char *result) );
-                                                                lfds711_pal_uint_t size) );
+  void [[r7.1.1:function libtest_testsuite_cleanup|libtest_testsuite_cleanup]]( struct libtest_testsuite_state *ts );
+ void [[r7.1.1:function libtest_testsuite_run|libtest_testsuite_run]]( struct libtest_testsuite_state *ts,
+                             struct libtest_results_state *rs );
-  void [[r7.1.1:function libshared_memory_add_memory|libshared_memory_add_memory]]( struct libshared_memory_state *ms,
+  void [[r7.1.1:function libtest_results_init|libtest_results_init]]( struct libtest_results_state *rs );
-                                   void *memory,
+ void [[r7.1.1:function libtest_results_cleanup|libtest_results_cleanup]]( struct libtest_results_state *rs );
-                                   lfds711_pal_uint_t memory_size_in_bytes );
+ void [[r7.1.1:function libtest_results_get_result|libtest_results_get_result]]( struct libtest_results_state *rs,
-  void [[r7.1.1:function libshared_memory_add_memory_from_numa_node|libshared_memory_add_memory_from_numa_node]]( struct libshared_memory_state *ms,
+                                  enum libtest_test_id test_id,
-                                                  lfds711_pal_uint_t numa_node_id,
+                                  enum lfds711_misc_validity *result );
-                                                  void *memory,
-                                                  lfds711_pal_uint_t memory_size_in_bytes );
+  void [[r7.1.1:function libtest_misc_determine_erg|libtest_misc_determine_erg]]( struct libshared_memory_state *ms,
+                                  lfds711_pal_uint_t (*count_array)[10],
+                                  enum libtest_misc_determine_erg_result *der,
+                                  lfds711_pal_uint_t *erg_length_in_bytes );
 ==Overview==
-All ''liblfds'' libraries are written such that they perform no memory allocations.  This is straightforward for ''liblfds'', where the user passes in state structures and so on, but it is problematic for ''libtest'' and ''libbenchmark'' as the store they require varies depending on the number of logical cores in the system, where that number cannot be known in advance, and where the work being done is complex enough that it is impractical to require the user to pass in the required store to functions - rather, a generic method is needed, where the libraries can in effect perform dynamic memory allocation.
+To run the tests, take the following steps;
-This is the purpose of the ''libshared_memory'' API.  The caller of ''libtest'' or ''libbenchmark'' functionality initializes a ''struct libshared_memory_state'', performs some memory allocation by whatever means are available and adds the pointer to that memory and its size in bytes to the memory state.  This memory state is then passed into such function in ''libtest'' or ''libbenchmark'' which require it, which in turn draw upon the memory so provided for dynamic allocations.
-The ''libtest'' library is not currently NUMA aware - it simply runs one thread per logical core and allocates everything from the allocation with the most free space at the time of the allocation request.  The ''libbenchmark'' library ''is'' NUMA aware and on NUMA systems in fact ''requires'' an allocation from every NUMA node in the system.
+# Initialize a ''struct libshared_memory_state'', with enough store (at least 4mb).  The test code is not NUMA aware, so no special NUMA-aware allocations are required.
+# Initialize a ''struct libtest_results_state''.
+# Initialize a ''struct libtest_testsuite'', passing in the ''libshared_memory_state'' initialized earlier.
+# Call ''libtest_testsuite_run'', passing in the ''struct libtest_testsuite_state'' and the ''struct libtest_results_state''.
-On SMP systems, or on NUMA systems but where a non-NUMA aware allocator is used (e.g. ''malloc'' rather than say ''numa_alloc_onnode'') memory is added by the ''libshared_memory_add_memory'' function.  On NUMA systems, memory is added with the ''libshared_memory_add_memory_from_numa_node'' function.  Any number of allocations from any number of nodes (or from the non-NUMA aware allocators) can be provided, although there's no obvious use case for this, since normal usage is to initialize and allocate per-NUMA node and then call a ''libtest'' or ''libenchmark'' function.
+When ''libtest_testsuite_run'' returns, the ''struct libtest_results_state'' will be populated, and it can be queried with ''libtest_results_get_result''.
-The ''libbenchmark_topology'' API offers an iterator API, which permits easy iteration over the NUMA nodes in a system, saving the caller the trouble of having to enumerate the processor/memory topology.  Note that initializing a topology state requires an initialized and populated memory state; however, this state is not NUMA sensitive, and so it can be allocated using malloc and then, once obtained, a second memory state can be populated with per-NUMA node allocations.
+A given initialized ''struct libtest_testsuite'' can be passed any number of times to ''libtest_testsuite_run''.  The ''struct libtest_results'' however must be initialized, or a new struct provided, between calls, as this structure only stores the results of a single test run.
 ==See Also==
-* [[r7.1.1:Usage Guide (benchmarking)|Usage Guide (benchmarking)]]
 * [[r7.1.1:Usage Guide (testing)|Usage Guide (testing)]]