:orphan: .. index:: pair: group; Test API to control a network throughput test tool .. _doxid-group__tapi__performance: Test API to control a network throughput test tool ================================================== .. toctree:: :hidden: enum_tapi_perf_bench.rst enum_tapi_perf_error.rst enum_tapi_perf_report_kind.rst struct_tapi_perf_app.rst struct_tapi_perf_client.rst struct_tapi_perf_client_methods.rst struct_tapi_perf_opts.rst struct_tapi_perf_report.rst struct_tapi_perf_server.rst struct_tapi_perf_server_methods.rst Overview ~~~~~~~~ Generic high level test API to control a network throughput test tool. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef enum :ref:`tapi_perf_bench` :ref:`tapi_perf_bench`; typedef enum :ref:`tapi_perf_error` :ref:`tapi_perf_error`; typedef enum :ref:`tapi_perf_report_kind` :ref:`tapi_perf_report_kind`; typedef struct :ref:`tapi_perf_report` :ref:`tapi_perf_report`; typedef struct :ref:`tapi_perf_server` :ref:`tapi_perf_server`; typedef struct :ref:`tapi_perf_opts` :ref:`tapi_perf_opts`; typedef void (*:ref:`tapi_perf_server_method_build_args`)( te_vec *args, const tapi_perf_opts *options ); typedef :ref:`te_errno` (*:ref:`tapi_perf_server_method_get_report`)( tapi_perf_server *server, tapi_perf_report_kind kind, tapi_perf_report *report ); typedef struct :ref:`tapi_perf_server_methods` :ref:`tapi_perf_server_methods`; typedef struct :ref:`tapi_perf_client` :ref:`tapi_perf_client`; typedef void (*:ref:`tapi_perf_client_method_build_args`)( te_vec *args, const tapi_perf_opts *options ); typedef :ref:`te_errno` (*:ref:`tapi_perf_client_method_wait`)( tapi_perf_client *client, int16_t timeout ); typedef :ref:`te_errno` (*:ref:`tapi_perf_client_method_get_report`)( tapi_perf_client *client, tapi_perf_report_kind kind, tapi_perf_report *report ); typedef struct :ref:`tapi_perf_client_methods` :ref:`tapi_perf_client_methods`; typedef struct :ref:`tapi_perf_app` :ref:`tapi_perf_app`; // enums enum :ref:`tapi_perf_bench`; enum :ref:`tapi_perf_error`; enum :ref:`tapi_perf_report_kind`; // structs struct :ref:`tapi_perf_app`; struct :ref:`tapi_perf_client`; struct :ref:`tapi_perf_client_methods`; struct :ref:`tapi_perf_opts`; struct :ref:`tapi_perf_report`; struct :ref:`tapi_perf_server`; struct :ref:`tapi_perf_server_methods`; // global functions void :ref:`tapi_perf_opts_init`(:ref:`tapi_perf_opts`* opts); :ref:`tapi_perf_server`* :ref:`tapi_perf_server_create`(:ref:`tapi_perf_bench` bench, const :ref:`tapi_perf_opts`* options, :ref:`tapi_job_factory_t`* factory); void :ref:`tapi_perf_server_destroy`(:ref:`tapi_perf_server`* server); :ref:`te_errno` :ref:`tapi_perf_server_start_unreliable`(:ref:`tapi_perf_server`* server); :ref:`te_errno` :ref:`tapi_perf_server_start`(:ref:`tapi_perf_server`* server); :ref:`te_errno` :ref:`tapi_perf_server_stop`(:ref:`tapi_perf_server`* server); :ref:`te_errno` :ref:`tapi_perf_server_get_report`(:ref:`tapi_perf_server`* server, :ref:`tapi_perf_report`* report); :ref:`te_errno` :ref:`tapi_perf_server_get_specific_report`(:ref:`tapi_perf_server`* server, :ref:`tapi_perf_report_kind` kind, :ref:`tapi_perf_report`* report); :ref:`te_errno` :ref:`tapi_perf_server_check_report`(:ref:`tapi_perf_server`* server, :ref:`tapi_perf_report`* report, const char* tag); :ref:`te_errno` :ref:`tapi_perf_server_get_check_report`(:ref:`tapi_perf_server`* server, const char* tag, :ref:`tapi_perf_report`* report); :ref:`te_errno` :ref:`tapi_perf_server_get_dump_check_report`(:ref:`tapi_perf_server`* server, const char* tag, :ref:`tapi_perf_report`* report); :ref:`tapi_perf_client`* :ref:`tapi_perf_client_create`(:ref:`tapi_perf_bench` bench, const :ref:`tapi_perf_opts`* options, :ref:`tapi_job_factory_t`* factory); void :ref:`tapi_perf_client_destroy`(:ref:`tapi_perf_client`* client); :ref:`te_errno` :ref:`tapi_perf_client_start`(:ref:`tapi_perf_client`* client); :ref:`te_errno` :ref:`tapi_perf_client_stop`(:ref:`tapi_perf_client`* client); :ref:`te_errno` :ref:`tapi_perf_client_wait`(:ref:`tapi_perf_client`* client, int16_t timeout); :ref:`te_errno` :ref:`tapi_perf_client_get_report`(:ref:`tapi_perf_client`* client, :ref:`tapi_perf_report`* report); :ref:`te_errno` :ref:`tapi_perf_client_get_specific_report`(:ref:`tapi_perf_client`* client, :ref:`tapi_perf_report_kind` kind, :ref:`tapi_perf_report`* report); :ref:`te_errno` :ref:`tapi_perf_client_check_report`(:ref:`tapi_perf_client`* client, :ref:`tapi_perf_report`* report, const char* tag); :ref:`te_errno` :ref:`tapi_perf_client_get_check_report`(:ref:`tapi_perf_client`* client, const char* tag, :ref:`tapi_perf_report`* report); :ref:`te_errno` :ref:`tapi_perf_client_get_dump_check_report`(:ref:`tapi_perf_client`* client, const char* tag, :ref:`tapi_perf_report`* report); const char* :ref:`tapi_perf_error2str`(:ref:`tapi_perf_error` error); const char* :ref:`tapi_perf_bench2str`(:ref:`tapi_perf_bench` bench); static const char* :ref:`tapi_perf_server_get_name`(const :ref:`tapi_perf_server`* server); static const char* :ref:`tapi_perf_client_get_name`(const :ref:`tapi_perf_client`* client); void :ref:`tapi_perf_log_report`(const :ref:`tapi_perf_server`* server, const :ref:`tapi_perf_client`* client, const :ref:`tapi_perf_report`* report, const char* test_params); void :ref:`tapi_perf_log_cumulative_report`(const :ref:`tapi_perf_server`* server[], const :ref:`tapi_perf_client`* client[], const :ref:`tapi_perf_report`* report[], int number_of_instances, const char* test_params); bool :ref:`tapi_perf_opts_cmp`(const :ref:`tapi_perf_opts`* opts_a, const :ref:`tapi_perf_opts`* opts_b); // macros #define :ref:`TAPI_PERF_BENCH_MAPPING_LIST` #define :ref:`TAPI_PERF_INTERVAL_DISABLED` #define :ref:`TAPI_PERF_TIMEOUT_DEFAULT` #define :ref:`TEST_GET_PERF_BENCH`(var_name_) .. _details-group__tapi__performance: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Generic high level test API to control a network throughput test tool. Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved. .. _doxid-group__tapi__performance_1tapi_performance_notes: Notes ~~~~~ Throughput value should be obtained from receiver (usually it is a server instance until it is changed by traffic direction options) You have to restart a server along with a client if you need to perform a few measurements in a row, otherwise the server returns a report of the first measurement all the time (until restarting or destroying) .. _doxid-group__tapi__performance_1tapi_performance_example: Example of usage ~~~~~~~~~~~~~~~~ Lets assume we need to send ``UDP`` traffic with iperf. We need to check the result throughput with the following input options: ``total bandwidth`` = ``1000 Mbit/s``, ``streams`` = ``5``, and ``test duration`` = ``60 sec``. Server iperf should use any free port on the host, and its host address is ``192.168.1.1``. So, we have the following commands for both server and client: ``iperf -s -u -p 60000`` ``iperf -c 192.168.1.1 -p 60000 -u -b 200 -P 5 -t 60`` .. ref-code-block:: cpp #include "tapi_job.h" #include "tapi_job_factory_rpc.h" #include "tapi_performance.h" int main(int argc, char *argv[]) { :ref:`tapi_perf_server ` *perf_server = NULL; :ref:`tapi_perf_client ` *perf_client = NULL; :ref:`tapi_perf_opts ` perf_opts; :ref:`tapi_perf_report ` perf_server_report; :ref:`tapi_perf_report ` perf_client_report; :ref:`rcf_rpc_server ` *perf_server_rpcs; :ref:`rcf_rpc_server ` *perf_client_rpcs; :ref:`tapi_job_factory_t ` *client_factory = NULL; :ref:`tapi_job_factory_t ` *server_factory = NULL; :ref:`TEST_START `; // Set default perf options :ref:`tapi_perf_opts_init `(&perf_opts); // Set test specific perf options perf_opts.:ref:`host ` = "192.168.1.1"; perf_opts.:ref:`protocol ` = IPPROTO_UDP; perf_opts.:ref:`port ` = :ref:`tapi_get_port `(perf_server_rpcs); perf_opts.:ref:`streams ` = 5; perf_opts.:ref:`bandwidth_bits ` = TE_UNITS_DEC_M2U(1000) / perf_opts.:ref:`streams `; perf_opts.:ref:`duration_sec ` = 60; // To force server to print a report at the end of test even if it lost // connection with client (iperf tool issue, Bug 9714) perf_opts.:ref:`interval_sec ` = perf_opts.:ref:`duration_sec `; :ref:`CHECK_RC `(:ref:`tapi_job_factory_rpc_create `(perf_server_rpcs, &server_factory)); :ref:`CHECK_RC `(:ref:`tapi_job_factory_rpc_create `(perf_client_rpcs, &client_factory)); perf_server = :ref:`tapi_perf_server_create `(:ref:`TAPI_PERF_IPERF `, &perf_opts, server_factory); perf_client = :ref:`tapi_perf_client_create `(:ref:`TAPI_PERF_IPERF `, &perf_opts, client_factory); :ref:`CHECK_RC `(:ref:`tapi_perf_server_start `(perf_server)); :ref:`CHECK_RC `(:ref:`tapi_perf_client_start `(perf_client)); :ref:`CHECK_RC `(:ref:`tapi_perf_client_wait `(perf_client, :ref:`TAPI_PERF_TIMEOUT_DEFAULT `)); // Time is relative and goes differently on different hosts. // Sometimes we need to wait for a few moments until report is ready. :ref:`VSLEEP `(1, "ensure perf server has printed its report"); :ref:`CHECK_RC `(:ref:`tapi_perf_client_get_dump_check_report `(perf_client, "client", &perf_client_report)); :ref:`CHECK_RC `(:ref:`tapi_perf_server_get_dump_check_report `(perf_server, "server", &perf_server_report)); // Analyze the obtained reports ... :ref:`TEST_SUCCESS `; cleanup: :ref:`tapi_perf_client_destroy `(perf_client); :ref:`tapi_perf_server_destroy `(perf_server); :ref:`tapi_job_factory_destroy `(client_factory); :ref:`tapi_job_factory_destroy `(server_factory); :ref:`TEST_END `; } Typedefs -------- .. index:: pair: typedef; tapi_perf_bench .. _doxid-group__tapi__performance_1ga733b62e2ffd8fd125393741d2981eb96: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`tapi_perf_bench` tapi_perf_bench Supported network throughput test tools list. .. index:: pair: typedef; tapi_perf_error .. _doxid-group__tapi__performance_1ga39625d8c5b14d914a9b3e62797c0afb3: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`tapi_perf_error` tapi_perf_error List of possible network throughput test tool errors. .. index:: pair: typedef; tapi_perf_report_kind .. _doxid-group__tapi__performance_1ga11a9f241023155ae1e521f7254a117c2: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`tapi_perf_report_kind` tapi_perf_report_kind List of possible report kinds. .. index:: pair: typedef; tapi_perf_report .. _doxid-group__tapi__performance_1ga38084b500a4f3ed4d1f26f9079b1ce58: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_perf_report` tapi_perf_report Network throughput test tool report. .. index:: pair: typedef; tapi_perf_server .. _doxid-group__tapi__performance_1gad4d2b515db568d6f751e92fe711cdfec: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_perf_server` tapi_perf_server Network throughput test server tool context .. index:: pair: typedef; tapi_perf_opts .. _doxid-group__tapi__performance_1ga64c9c5a3f0239f204aca322677f99bbe: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_perf_opts` tapi_perf_opts Network throughput test tool options .. index:: pair: typedef; tapi_perf_server_method_build_args .. _doxid-group__tapi__performance_1ga388c903c215e7ccfb629671d40f29feb: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef void (*tapi_perf_server_method_build_args)( te_vec *args, const tapi_perf_opts *options ) Build command string to run server tool. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - args - List of built commands line arguments. * - options - Tool server options. .. index:: pair: typedef; tapi_perf_server_method_get_report .. _doxid-group__tapi__performance_1ga792fb1e662688ee387c0a338f71002c3: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`te_errno` (*tapi_perf_server_method_get_report)( tapi_perf_server *server, tapi_perf_report_kind kind, tapi_perf_report *report ) Get server report. The function reads client output (stdout, stderr). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. * - report - Report with results. .. rubric:: Returns: Status code. .. index:: pair: typedef; tapi_perf_server_methods .. _doxid-group__tapi__performance_1ga427ffa9a7e9c2a4a9f3e6eeb139496ac: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_perf_server_methods` tapi_perf_server_methods Methods to operate the server network throughput test tool. .. index:: pair: typedef; tapi_perf_client .. _doxid-group__tapi__performance_1gac0d15df36459a1f29e245793f9252b35: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_perf_client` tapi_perf_client Network throughput test client tool context .. index:: pair: typedef; tapi_perf_client_method_build_args .. _doxid-group__tapi__performance_1gadfa1a10c9ed1be09824917fba43684b7: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef void (*tapi_perf_client_method_build_args)( te_vec *args, const tapi_perf_opts *options ) Build command string to run client tool. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - args - List of built commands line arguments. * - options - Tool client options. .. index:: pair: typedef; tapi_perf_client_method_wait .. _doxid-group__tapi__performance_1ga0b71a5ac2acc003b39f3ca2ff2e8c23b: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`te_errno` (*tapi_perf_client_method_wait)( tapi_perf_client *client, int16_t timeout ) Wait while client finishes his work. Note, function jumps to cleanup if timeout is expired. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - timeout - Time to wait for client results (seconds). It MUST be big enough to finish client normally (it depends on client's options), otherwise the function will be failed. Use :ref:`TAPI_PERF_TIMEOUT_DEFAULT ` to coerce the function to calculate the required timeout value. .. rubric:: Returns: Status code. .. index:: pair: typedef; tapi_perf_client_method_get_report .. _doxid-group__tapi__performance_1ga81efa85dac9ee2e6b5b138da48b84d96: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`te_errno` (*tapi_perf_client_method_get_report)( tapi_perf_client *client, tapi_perf_report_kind kind, tapi_perf_report *report ) Get client report. The function reads client output (stdout, stderr). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - report - Report with results. .. rubric:: Returns: Status code. .. index:: pair: typedef; tapi_perf_client_methods .. _doxid-group__tapi__performance_1ga9572bf5d3eb55e499353a1c8a530c02d: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_perf_client_methods` tapi_perf_client_methods Methods to operate the client network throughput test tool. .. index:: pair: typedef; tapi_perf_app .. _doxid-group__tapi__performance_1gadc2b36f2446d72c0fc5747f97140f8e4: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_perf_app` tapi_perf_app Network throughput test tool context (common for both server and client) Global Functions ---------------- .. index:: pair: function; tapi_perf_opts_init .. _doxid-group__tapi__performance_1gac664f2f21af0c8edf88f3ed5c913160e: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_perf_opts_init(:ref:`tapi_perf_opts`* opts) Initialize options with default values (from point of view of perf tool). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - opts - Network throughput test tool options. .. index:: pair: function; tapi_perf_server_create .. _doxid-group__tapi__performance_1ga41abb8c1cb2cd9f985e68e84f03205ab: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`tapi_perf_server`* tapi_perf_server_create(:ref:`tapi_perf_bench` bench, const :ref:`tapi_perf_opts`* options, :ref:`tapi_job_factory_t`* factory) Create server network throughput test tool proxy. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - bench - Sort of tool, see :ref:`tapi_perf_bench ` to get a list of supported tools. * - options - Server tool specific options, may be ``NULL``, to set them to default, further you can edit them using return value. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_server_destroy ` .. index:: pair: function; tapi_perf_server_destroy .. _doxid-group__tapi__performance_1ga37dc0171f0a9561a3a562ccfd22618a1: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_perf_server_destroy(:ref:`tapi_perf_server`* server) Destroy server network throughput test tool proxy. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. .. rubric:: See also: :ref:`tapi_perf_server_create ` .. index:: pair: function; tapi_perf_server_start_unreliable .. _doxid-group__tapi__performance_1ga75da37521cbb9c0109e970f83a9d60bc: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_start_unreliable(:ref:`tapi_perf_server`* server) Start perf server. It returns immediately after run the command starting the server. It can be unreliable to call :ref:`tapi_perf_client_start() ` just after this function because server can not be ready to accept clients by this time, especially on slow machine. It is recommended to use this function only if there will be some delay before starting a client, otherwise use :ref:`tapi_perf_server_start() ` instead. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_server_start `, :ref:`tapi_perf_server_stop ` .. index:: pair: function; tapi_perf_server_start .. _doxid-group__tapi__performance_1gad646e9498ba138a4f3fbf41cb465766b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_start(:ref:`tapi_perf_server`* server) Start perf server "reliably". It calls :ref:`tapi_perf_server_start_unreliable() ` and wait until it is ready to accept clients. Note, it is not true reliable because it doesn't check whether server is ready, or not, it just waits for some time. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_server_start_unreliable `, :ref:`tapi_perf_server_stop ` .. index:: pair: function; tapi_perf_server_stop .. _doxid-group__tapi__performance_1ga71ea20019296f30ce905107c70aef65d: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_stop(:ref:`tapi_perf_server`* server) Stop perf server. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_server_start ` .. index:: pair: function; tapi_perf_server_get_report .. _doxid-group__tapi__performance_1ga2b2cdea5ce8f1c23b4ff26225f126ab2: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_get_report(:ref:`tapi_perf_server`* server, :ref:`tapi_perf_report`* report) Get server report. The function reads server output (stdout, stderr). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. * - report - Report with results. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_perf_server_get_specific_report .. _doxid-group__tapi__performance_1gac450e0d906adfb6c37facafd96b73b51: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_get_specific_report(:ref:`tapi_perf_server`* server, :ref:`tapi_perf_report_kind` kind, :ref:`tapi_perf_report`* report) Get server report of specified kind. The function reads server output (stdout, stderr). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. * - kind - Report kind, e.g. default or receiver's, or sender's. * - report - Report with results. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_perf_server_check_report .. _doxid-group__tapi__performance_1ga0e97066c85aa51fcd78eb0b3c04d002e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_check_report(:ref:`tapi_perf_server`* server, :ref:`tapi_perf_report`* report, const char* tag) Check server report for errors. The function prints verdicts in case of errors are presents in the ``report``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. * - report - Server report. * - tag - Tag to print in verdict message. .. rubric:: Returns: Status code. It returns non-zero code if there are errors in the report. .. index:: pair: function; tapi_perf_server_get_check_report .. _doxid-group__tapi__performance_1ga4bf178431b286bc6c1b676893ffe1750: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_get_check_report(:ref:`tapi_perf_server`* server, const char* tag, :ref:`tapi_perf_report`* report) Get server report and check it for errors. The function is a wrapper which calls :ref:`tapi_perf_server_get_report() ` and :ref:`tapi_perf_server_check_report() ` .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. * - tag - Tag to print in verdict message. * - report - Report with results, it may be ``NULL`` if you don't care about results, but only errors. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_server_get_report `, :ref:`tapi_perf_server_check_report `, :ref:`tapi_perf_server_get_dump_check_report ` .. index:: pair: function; tapi_perf_server_get_dump_check_report .. _doxid-group__tapi__performance_1ga143f417142509731da6a91063e62ab46: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_server_get_dump_check_report(:ref:`tapi_perf_server`* server, const char* tag, :ref:`tapi_perf_report`* report) Get server report, dump it to log and check for errors. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. * - tag - Tag to print in both verdict and dump messages. * - report - Report with results, it may be ``NULL`` if you don't care about results, but only errors. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_server_get_report `, :ref:`tapi_perf_server_check_report `, :ref:`tapi_perf_server_get_check_report ` .. index:: pair: function; tapi_perf_client_create .. _doxid-group__tapi__performance_1ga6298bd45c6c89e7cbee5252238bbc8bc: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`tapi_perf_client`* tapi_perf_client_create(:ref:`tapi_perf_bench` bench, const :ref:`tapi_perf_opts`* options, :ref:`tapi_job_factory_t`* factory) Create client network throughput test tool proxy. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - bench - Sort of tool, see :ref:`tapi_perf_bench ` to get a list of supported tools. * - options - Client tool specific options, may be ``NULL``, to set them to default, further you can edit them using return value. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_client_destroy ` .. index:: pair: function; tapi_perf_client_destroy .. _doxid-group__tapi__performance_1gafd8c1610e610c4cd01cef19bc2776b64: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_perf_client_destroy(:ref:`tapi_perf_client`* client) Destroy client network throughput test tool proxy. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. .. rubric:: See also: :ref:`tapi_perf_client_create ` .. index:: pair: function; tapi_perf_client_start .. _doxid-group__tapi__performance_1gadf301641fb7d3badde2406fdb4916cbc: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_start(:ref:`tapi_perf_client`* client) Start perf client. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_client_stop ` .. index:: pair: function; tapi_perf_client_stop .. _doxid-group__tapi__performance_1gae52788f14c5590dddf8fa853e6aa6c93: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_stop(:ref:`tapi_perf_client`* client) Stop perf client. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_client_start ` .. index:: pair: function; tapi_perf_client_wait .. _doxid-group__tapi__performance_1gada0cd5dde24816eb378534d5b979a912: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_wait(:ref:`tapi_perf_client`* client, int16_t timeout) Wait while client finishes his work. Note, function jumps to cleanup if timeout is expired. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - timeout - Time to wait for client results (seconds). It MUST be big enough to finish client normally (it depends on client's options), otherwise the function will be failed. Use :ref:`TAPI_PERF_TIMEOUT_DEFAULT ` to coerce the function to calculate the required timeout value. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_perf_client_get_report .. _doxid-group__tapi__performance_1ga229d87e6a50f2aa83f14e044e0f1d217: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_get_report(:ref:`tapi_perf_client`* client, :ref:`tapi_perf_report`* report) Get client report. The function reads client output (stdout, stderr). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - report - Report with results. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_perf_client_get_specific_report .. _doxid-group__tapi__performance_1gac23126a6038a9fd1bdc585d09c077c8a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_get_specific_report(:ref:`tapi_perf_client`* client, :ref:`tapi_perf_report_kind` kind, :ref:`tapi_perf_report`* report) Get client report of specified kind. The function reads client output (stdout, stderr). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - kind - Report kind, e.g. default or receiver's, or sender's. * - report - Report with results. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_perf_client_check_report .. _doxid-group__tapi__performance_1gaf9cfbf626f449a3dd0cd38fd12b4cc89: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_check_report(:ref:`tapi_perf_client`* client, :ref:`tapi_perf_report`* report, const char* tag) Check client report for errors. The function prints verdicts in case of errors are presents in the ``report``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - report - Client report. * - tag - Tag to print in verdict message. .. rubric:: Returns: Status code. It returns non-zero code if there are errors in the report. .. index:: pair: function; tapi_perf_client_get_check_report .. _doxid-group__tapi__performance_1gabb9df23b1d935a22fd3f715359340cf7: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_get_check_report(:ref:`tapi_perf_client`* client, const char* tag, :ref:`tapi_perf_report`* report) Get client report and check it for errors. The function is a wrapper which calls :ref:`tapi_perf_client_get_report() ` and :ref:`tapi_perf_client_check_report() ` .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - tag - Tag to print in verdict message. * - report - Report with results, it may be ``NULL`` if you don't care about results, but only errors. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_client_get_report `, :ref:`tapi_perf_client_check_report `, :ref:`tapi_perf_client_get_dump_check_report ` .. index:: pair: function; tapi_perf_client_get_dump_check_report .. _doxid-group__tapi__performance_1ga716f5a3ebedb1875836659d6db384edf: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_perf_client_get_dump_check_report(:ref:`tapi_perf_client`* client, const char* tag, :ref:`tapi_perf_report`* report) Get client report, dump it to log and check for errors. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. * - tag - Tag to print in both verdict and dump messages. * - report - Report with results, it may be ``NULL`` if you don't care about results, but only errors. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_perf_client_get_report `, :ref:`tapi_perf_client_check_report `, :ref:`tapi_perf_client_get_check_report ` .. index:: pair: function; tapi_perf_error2str .. _doxid-group__tapi__performance_1ga74be102ef7977dba74916ead71729cfb: .. ref-code-block:: cpp :class: doxyrest-title-code-block const char* tapi_perf_error2str(:ref:`tapi_perf_error` error) Get error description. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - error - Error code. .. rubric:: Returns: Error code string representation. .. index:: pair: function; tapi_perf_bench2str .. _doxid-group__tapi__performance_1ga26630d39ae4bb583926cd4420e0e4325: .. ref-code-block:: cpp :class: doxyrest-title-code-block const char* tapi_perf_bench2str(:ref:`tapi_perf_bench` bench) Get string representation of ``bench``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - bench - Tool's sort. .. rubric:: Returns: Tool's sort name. .. index:: pair: function; tapi_perf_server_get_name .. _doxid-group__tapi__performance_1gaa3199cf4d255d829e365f66a06892cdd: .. ref-code-block:: cpp :class: doxyrest-title-code-block static const char* tapi_perf_server_get_name(const :ref:`tapi_perf_server`* server) Get server network throughput test tool name. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. .. rubric:: Returns: Server tool name. .. index:: pair: function; tapi_perf_client_get_name .. _doxid-group__tapi__performance_1gaeb1517217af83aebf9ffbf827e593e1d: .. ref-code-block:: cpp :class: doxyrest-title-code-block static const char* tapi_perf_client_get_name(const :ref:`tapi_perf_client`* client) Get client network throughput test tool name. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - client - Client context. .. rubric:: Returns: Client tool name. .. index:: pair: function; tapi_perf_log_report .. _doxid-group__tapi__performance_1gabf93f530253e592b0f21d4b1170d2466: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_perf_log_report(const :ref:`tapi_perf_server`* server, const :ref:`tapi_perf_client`* client, const :ref:`tapi_perf_report`* report, const char* test_params) Print a network throughput test tool report. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - Server context. * - client - Client context. * - report - Report. * - test_params - Test specific params; It should be represented in the form of comma-separated pairs "param=value". .. index:: pair: function; tapi_perf_log_cumulative_report .. _doxid-group__tapi__performance_1ga84ea5206c8ab8c94537d2646b194e8bc: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_perf_log_cumulative_report(const :ref:`tapi_perf_server`* server[], const :ref:`tapi_perf_client`* client[], const :ref:`tapi_perf_report`* report[], int number_of_instances, const char* test_params) Print a network throughput test tool report by adding throughput of all server/client pairs. Note, that we expect server/client pairs to run roughly the same traffic, see perf_opts_cmp() for details. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - server - List of server contexts. * - client - List of client contexts. * - report - List of reports (user decides which one is taken where). * - number_of_instances - Number of instances in the above 3 lists * - test_params - Test specific params; It should be represented in the form of comma-separated pairs "param=value". .. index:: pair: function; tapi_perf_opts_cmp .. _doxid-group__tapi__performance_1ga0cb1dd2a292a8eb65c733003e308ffd9: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool tapi_perf_opts_cmp(const :ref:`tapi_perf_opts`* opts_a, const :ref:`tapi_perf_opts`* opts_b) Compare important parts of the run. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - opts_a - First object for comparison * - opts_b - Second object for comparison .. rubric:: Returns: ``true`` if objects' important properties are equal, ``false`` if not Macros ------ .. index:: pair: define; TAPI_PERF_BENCH_MAPPING_LIST .. _doxid-group__tapi__performance_1ga7759d5911b8a2a53f4f40778cc17eeb2: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_PERF_BENCH_MAPPING_LIST The list of values allowed for parameter of type 'tapi_perf_bench' .. index:: pair: define; TAPI_PERF_INTERVAL_DISABLED .. _doxid-group__tapi__performance_1ga206fc153a75dd673ff609c25479683cc: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_PERF_INTERVAL_DISABLED Disable periodic bandwidth reports. .. index:: pair: define; TAPI_PERF_TIMEOUT_DEFAULT .. _doxid-group__tapi__performance_1ga72902dd6c37da094533275ac26307a2a: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_PERF_TIMEOUT_DEFAULT Default timeout to client wait method. It means the real timeout will be calculated according to tool's options. .. index:: pair: define; TEST_GET_PERF_BENCH .. _doxid-group__tapi__performance_1ga999bfa9a3431e7e5a3ba903e785f03ac: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TEST_GET_PERF_BENCH(var_name_) Get the value of parameter of type 'tapi_perf_bench' .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - var_name\_ - Name of the variable used to get the value of "var_name\_" parameter of type 'tapi_perf_bench' (OUT)