From 065a2b322e39002e9b639d3d87520cde4e1f010e Mon Sep 17 00:00:00 2001 From: Florian Lindner Date: Tue, 20 Jun 2023 22:42:24 +0200 Subject: [PATCH] doc: Add section about using benchmarks for tests to the README.md of the backend_odbc plugin - explain why only basic unit tests are present - add --help arguement to the benchmark_mountpoint - update documentation --- benchmarks/mountpoint.c | 26 +++++++++++++++-- src/plugins/backend_odbc/README.md | 29 +++++++++++++++++++ .../backend_odbc/backend_odbc_helpers.c | 13 +++++++-- 3 files changed, 62 insertions(+), 6 deletions(-) diff --git a/benchmarks/mountpoint.c b/benchmarks/mountpoint.c index 97478405997..bfe26f1b153 100644 --- a/benchmarks/mountpoint.c +++ b/benchmarks/mountpoint.c @@ -33,10 +33,25 @@ char * metaValueFormat = "metav%zu"; char * metaValueModifiedFormat = "memod%zu"; +static void printHelp (void) +{ + puts ("Optional arguments:"); + puts ("-c or --key-count : Specify the number of keys to benchmark."); + puts ("-H or --harmonize-names"); + puts ("-h or --help: display this help"); + puts ("-s or --single-keysets: Store each key in its own KeySet for Benchmark 1"); + puts ("-m or --with-meta: include benchmarks for metadata, for the most reliable results it is recommended to run the tests for " + "metadata separately (see -M)"); + puts ("-M or --only-meta: only run benchmarks for metadata"); + puts ("-v or --verbose: more detailed output"); + exit (EXIT_SUCCESS); +} + static bool processCommandLineArguments (int argc, char ** argv) { struct option long_options[] = { { "key-count", required_argument, 0, 'c' }, - { "harmonize-names", no_argument, 0, 'h' }, + { "harmonize-names", no_argument, 0, 'H' }, + { "help", no_argument, 0, 'h' }, { "single-keysets", no_argument, 0, 's' }, { "with-meta", no_argument, 0, 'm' }, { "only-meta", no_argument, 0, 'M' }, @@ -67,6 +82,9 @@ static bool processCommandLineArguments (int argc, char ** argv) break; } case 'h': + printHelp (); + break; + case 'H': harmonizeKeys = true; keyNameFormat = "key%08zu"; keyValueFormat = "value%08zu"; @@ -88,7 +106,8 @@ static bool processCommandLineArguments (int argc, char ** argv) verbose = true; break; default: - break; + fprintf (stderr, "The specified argument %c is not valid!", c); + printHelp (); } } @@ -105,7 +124,8 @@ int main (int argc, char ** argv) if (argc < 2) { - fprintf (stderr, "Usage: %s [options] \n", argv[0]); + fprintf (stderr, "Usage: %s [options] \n\n", argv[0]); + printHelp (); return EXIT_FAILURE; } diff --git a/src/plugins/backend_odbc/README.md b/src/plugins/backend_odbc/README.md index ab893dd38e0..2dd5f86e897 100644 --- a/src/plugins/backend_odbc/README.md +++ b/src/plugins/backend_odbc/README.md @@ -97,3 +97,32 @@ For unmounting, there is no new command necessary. Just use the well-known `kdb umount `, exactly like for the file-based backend. For more information about the ODBC backend, there is a tutorial available at [/doc/tutorials/odbc-backend.md](/doc/tutorials/odbc-backend.md). + +## Testing and Benchmarking + +There are no dedicated unit tests that actually store, read or delete data from +an ODBC data source. +The reason is, that with the current concept, a valid ODBC data source +definition (for unixODBC in `/etc/unixODBC/odbc.ini`) must be present. +We don't want to write to such an important system file that can influence other +applications. It would also be cumbersome if we require the user to set up a +specific ODBC configuration before running the tests . + +However, for basic functionality testing and performance evaluation, +you can create a valid ODBC mountpoint yourself using `kdb mountOdbc` +and then run the benchmark which is implemented in [/benchmarks/mountpoint.c](/benchmarks/mountpoint.c) +for the created mountpoint. +This approach makes it possible to test and benchmark any valid mountpoint in the KDB. +So different backends and plugins with different configurations can be tested and benchmarked. +Just create a mountpoint with the backends, plugins and configuration that you want and run +the benchmark with e.g. `bin/benchmark_mountpoint /benchmark` for this mountpoint. + +A short example that shows creating a new ODBC mountpoint and running benchmarks for KeySets and metadata: + +```sh +bin/kdb mountOdbc Selektra "" "" elektraKeys keyName keyValue metaKeys keyName metaKeyName metaKeyValue "" user:/odbcSqlite +bin/benchmark_mountpoint -c 1000 user:/odbcSqlite +bin/benchmark_mountpoint -Mc 1000 user:/odbcSqlite +``` + +More information about benchmarking is available at [/benchmarks/README.md](/benchmarks/README.md). diff --git a/src/plugins/backend_odbc/backend_odbc_helpers.c b/src/plugins/backend_odbc/backend_odbc_helpers.c index 09e17a3159d..eea2c0631f6 100644 --- a/src/plugins/backend_odbc/backend_odbc_helpers.c +++ b/src/plugins/backend_odbc/backend_odbc_helpers.c @@ -728,9 +728,9 @@ void clearDsConfig (struct dataSourceConfig * dsConfig, bool freeStrings) * @param freeDsConfigStrings only considered, if @p freeDsConfig is 'true', then it specifies if the strings * inside the dataSourceConfig struct should be freed too. * - * @retval 'false' if a NULL pointer was passed for @p sharedData or an error was reported by ODBC when trying to disconnect or free + * @retval false if a NULL pointer was passed for @p sharedData or an error was reported by ODBC when trying to disconnect or free * the handles. - * @retval 'true' otherwise. + * @retval true otherwise. */ bool clearOdbcSharedData (struct odbcSharedData * sharedData, bool freeDsConfig, bool freeDsConfigStrings) { @@ -779,7 +779,14 @@ bool clearOdbcSharedData (struct odbcSharedData * sharedData, bool freeDsConfig, } -/* Close the connection and free handles for connection and environment */ +/** + * @brief Close the connection and free handles for connection and environment + * @param plugin The plugin that contains the odbcSharedData struct which should be cleared + * @param[out] errorKey Used to add warnings. + * + * @retval true if the plugin data was NULL or the ODBC handles could be freed successfully + * @retval false if an error occurred + */ bool freeSharedHandles (Plugin * plugin, Key * errorKey) { struct odbcSharedData * sharedData = elektraPluginGetData (plugin);