EMA C++ Performace Tools Guide : 5 Interactive Provider Performance Tool : 5.5 EmaCppIProvPerf Configuration Options
 
5.5 EmaCppIProvPerf Configuration Options
EmaCppIProvPerf uses EmaConfig.xml configuration file to setup an EMA interactive provider and set of command line options to configure specific behavior of performance tool.
EmaConfig.xml must have IProvider section in the Provider group and appropriate Server section in Server group for correct configuration of the EMA interactive provider. For details on how to setup IProvider and Server sections, refer to the Enterprise Message API Configuration Guide. For examples of configuration, refer to Section 5.6.1.
EmaCppIProvPerf uses the command line option -providerName to specify name of Provider section.
 
Table 3: EmaCppIProvPerf Configuration Options  
COMMAND-LINE OPTION
DEFAULT
DESCRIPTION
-apiThreads
-1
Specifies the CPU core(s) to bind the internal EMA API thread(s) to dispatch received messages. The parameter is used when the application configures EMA to work in API dispatch mode (see -useUserDispatch). EmaCppIProvPerf does not bind the internal EMA API thread(s) to specific CPU core(s) by default. For details on the internal EMA API thread, refer to the Enterprise Message API Developers Guide, 2.4 Product Architecture.
Specifies the CPU physical mapping in format P:X C:Y T:Z, logical core ID (number), or no binding (-1).
Specifies the physical mapping which binds the thread to the specified physical processor, core, and thread (P:X C:Y T:Z). This syntax specifies a physical CPU to bind to. P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor. 
Specifying only one number causes a logical core ID to be bound instead of a physical one. -1 means no bind. 
For example, when specified as "1,3", the internal EMA API threads will be bound to logical CPU cores 1 and 3. 
The number of threads set by the parameter -threads should be matched. 
For details on rsslBindThread, refer to the Transport API C++ Edition Developers Guide.
-genericMsgLatencyRate
0
Sets the number of generic messages sent (per second) that contain latency data. This number must be less than or equal to the total generic message rate (see -genericMsgRate). When you set the value to“all” then latency data is added to each generic message.
-genericMsgRate
0
Sets the number of generic messages sent per second. This number cannot be less than the tick rate unless it is zero(see -tickRate).
-latencyFile
None
Specifies the name of the log file in which EmaCppIProvPerf logs the latency retrieved from individual latency updates, generic messages.
If a name is not specified, logging is disabled.
-latencyUpdateRate
10
Sets the number of updates sent per second containing latency information. This number must be less than or equal to the total update rate (see -updateRate).
NOTE: When you set the value “all” then latency data is added to each update message.
-mainThread
-1
Specifies the CPU core to bind the main application thread that controls working threads, collects and prints statistics. By default, EmaCppIProvPerf does not bind the main thread to specific CPU core.
Specifies the CPU physical mapping in format P:X C:Y T:Z, logical core ID (number), or no binding (-1).
Specifies the physical mapping which binds the thread to the specified physical processor, core, and thread (P:X C:Y T:Z). This syntax specifies a physical CPU to bind to. P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor. 
Specifying only one number causes a logical core ID to be bound instead of a physical one. -1 means no bind. 
For example, when specified "3", the main thread will be bound to logical CPU core 3. 
For details on rsslBindThread, refer to the Transport API C++ Edition Developers Guide.
-maxPackCount
1
Specifies maximum number of messages packed in a buffer (when count is greater than 1, packing is enabled).
-measureEncode
(no argument)
Configures EmaCppIProvPerf to measure encoding time of messages. By default, the measurement is not produced.
-measureDecode
(no argument)
Configures EmaCppIProvPerf to measure decoding time of messages. By default, the measurement is not produced.
-msgFile
MsgData.xml
Specifies the file that the provider uses to determine message content. For more details on input file information, refer to Section 8.1.
-nanoTime
(no argument)
Specifies the nanosecond precision for latency information instead of microsecond.
-noDisplayStats
(no argument)
Turns off printing statistics to the screen.
-packBufSize
6000
Sets size of buffer to use when message packing is enabled, i.e. maxPackCount > 1.
-providerName
Perf_Provider_
Specifies the name of provider in XML configuration file (EmaConfig.xml).
-preEnc
(no argument)
 
Specifies pre-encoding for updates and generic messages. All the template messages (see MsgData.xml) will be encoded before real sending. It decreases the time required for message preparation. By default, EmaCppIProvPerf encodes messages each time.
NOTE: Whenever a latency data is required, the messages that contain latency are encoded (see -genericMsgLatencyRate, -latencyUpdateRate).
-runTime
360
Sets the length of time EmaCppIProvPerf runs (in seconds).
-statsFile
ProvStats
Specifies the base name used to write the provider’s test statistics.
-summaryFile
ProvSummary.out
Specifies the base file name used to write the provider’s test summary.
-threads
None
The value of "-threads" serves two purposes: it defines the number of parallel threads/connections to be created AND where to bind each thread. For example, if an application wants to horizontally scale and open two connections, there should be two values for -threads: 0,1 OR P:0 C:0 T:0, P:0 C:0 T:1 OR -1, -1. The number of values specified indicates the number of threads to start (comma separated). The thread binding may be formatted or specified as follows: physical binding (P:X C:Y T:Z) OR logical binding (X) or -1 (no binding).
Physical binding: specify physical CPU to bind to: P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor.
Specifying only one number causes a logical core ID to be bound instead of a physical one. -1 means no bind. 
For example, when specified "1,3", it creates two threads to publish items respectively, and they are bound to CPU cores 1 and 3. 
In conjunction with -threads, one may specify -apiThreads and -workerThreads.
For details on rsslBindThread, refer to the Transport API Developers Guide.
-tickRate
1000
Sets the number of “ticks” (cycles completed by the provider’s main loop) per second. Adjusting the tick rate changes the size of update bursts: higher tick rates result in smaller individual bursts, creating smoother traffic.
-updateRate
100000
Configures the number of updates sent per second, per connection.
NOTE: This cannot be less than the tick rate, unless it is zero (see -tickRate).
-useUserDispatch
0
Configures how EmaCppIProvPerf and Enterprise Message API dispatch received messages. When you select 0 (API dispatch model) then EmaCppIProvPerf configures the Enterprise Message API to create an additional internal thread to dispatch received messages. When you select 1 (user dispatch model) the Enterprise Message API does not run a second thread and the EmaCppIProvPerf is responsible for dispatching all received messages. By default, EmaCppIProvPerf uses the API dispatch model.
For details on how an Enterprise Message API application dispatches received messages, refer to the Enterprise Message API Developers Guide.
-workerThreads
<none>
Sets the list of CPUs bound to Reactor worker threads.By default, EmaCppIProvPerf does not bind the Reactor worker thread(s) to specific CPU core(s). For details on Value Added Components, refer to the Transport API Value Added Components Developers Guide.
Specifies the CPU physical mapping in format P:X C:Y T:Z, logical core ID (number), or no binding (-1).
Specifies the physical mapping which binds the thread to the specified physical processor, core, and thread (P:X C:Y T:Z). This syntax specifies a physical CPU to bind to. P refers to processor, C refers to core, and T refers to thread. If T is not specified (or T:#), the thread will be bound to all threads on the specified processor. If C is not specified (or C:#), the thread will be bound to all cores and threads on that processor.
Specifying only one number causes a logical core ID to be bound instead of a physical one. -1 means no bind.
For example, “1,3” specifies two Reactor worker threads, respectively bound to logical CPU cores 1 and 3.
The number of threads set by the -threads parameter should be matched.
For details on rsslBindThread, refer to the Transport API Developers Guide.
-writeStatsInterval
5
Sets how often statistics are printed to the screen and statistics file (in seconds).