Using command-line options
==========================

You can set these options from the command-line; they affect only
the specific instance of the running server:

    --tcp_nodelay 1                TCP/IP NODELAY option
    --tcp_rcvbuf value             TCP/IP receive buffer, in bytes
    --tcp_sndbuf value             TCP/IP send buffer, in bytes
    --high_water 0                 High water mark for message flow control
    --low_water 0                  Low water mark for message flow control
    --direct 0                     Enables Direct Mode for connections
    --batching 32768               Maximum size of Direct Mode batches
    --on_overflow trim             Sets action for high-water overflow
    --chrono_enabled 1             Enable chrono pingbacks?
    --chrono_floor 100             Floor for chrono pingbacks
    --chrono_density 1             Sample density as permille
    --chrono_batch 150             Batch size for chrono pingbacks

Creating a configuration file
=============================

You can also set the above options in an XML text file, to affect
all future instances of the running server. To create a new XML
configuration file, copy the following block to an editor session,
and then:

 1. Delete all options you want to leave as default.
 2. Delete this comment and update your name and the date.
 3. Save file as new wireapi.cfg or merge with existing copy.
 4. Restart the server.

    <?xml version="1.0"?>
    <!--
        Revised: yyyy/mm/dd by yourname
     -->
    
    <config>
        <tuning
            tcp_nodelay = "1"
            tcp_rcvbuf = "value"
            tcp_sndbuf = "value"
            high_water = "0"
            low_water = "0"
            direct = "0"
        />
        <direct
            batching = "32768"
            on_overflow = "trim"
        />
        <chrono
            enabled = "1"
            floor = "100"
            density = "1"
            batch = "150"
        />
    </config>

Setting tuning options
===========================

tcp_nodelay = "1":
    If this value is 1, socket data is written immediately, which is     
    usually good for latency. If this value is 0, data is buffered until 
    there is a full packet, which is usually good for throughput. Default
    value is 1.                                                          
tcp_rcvbuf = "value":
    If this value is greater than zero, the connection to the server will
    use the specified value. Note: setting this value is delicate, do not
    use this option unless you know what you are doing. Default value is 
    not defined.                                                         
tcp_sndbuf = "value":
    If this value is greater than zero, the connection to the server will
    use the specified value. Note: setting this value is delicate, do not
    use this option unless you know what you are doing. Default value is 
    not defined.                                                         
high_water = "0":
    Number of messages in arrived queue when message flow from server is
    stopped. If this property is 0, message flow is never switched off. 
    Default value is 0.                                                 
low_water = "0":
    Number of messages in arrived queue when message flow from server is
    started again after it had been switched off on high water mark.    
    Default value is 0.                                                 
direct = "0":
    If set to 1, new connections will by default use Direct Mode.   
    Applications can override this by setting the connection->direct
    property on new connections. Default value is 0.                

Setting direct options
===========================

batching = "32768":
    Defines the maximum batch size for Direct Mode opportunistic batching
    on message sends. Setting this higher will improve throughput, and   
    usually with lower latency, but will cause higher memory consumption.
    Setting this to zero will switch off batching. Any value less than   
    2048 is treated as zero. Default value is 32768. Maximum value is    
    2097152.                                                             
on_overflow = "trim":
    Specifies how the WireAPI stack should handle an overflow condition, 
    as defined by the arrived message queue reaching the high-water mark.
    The allowed actions are: 'warn' - issue a message to the console,    
    'trim' - discard old messages to make space for new ones, 'drop' -   
    drop new incoming messages, and 'kill' - assert an error and kill the
    application. Default value is trim.                                  

Setting chrono options
===========================

enabled = "1":
    Specifies whether chrono pingbacks are enabled or not. If not, then
    any any chrono information in contents will be ignored. By default 
    chrono pingbacks are enabled. Default value is 1.                  
floor = "100":
    Specifies the floor for pingbacks. Only pingbacks that show an        
    end-to-end latency greater or equal to the floor will be reported. If 
    you set this to zero, all pingbacks will be reported. Default value is
    100.                                                                  
density = "1":
    Specifies the sampling density, as a permille. Valid values are 1 to  
    1000. By default 1/1000th of messages will be sampled. The sampling is
    randomized if the density is less than 1000 permille. Default value is
    1.                                                                    
batch = "150":
    Specifies the batching size for chrono pingback messages. These track 
    the latency of contents passing through the architecture. A chrono    
    pingback is about 15 characters long, so the default batch and        
    promille settings will result in one pingback message every 10,000    
    received messages. If you set the batch size too low, you may get     
    excessive back chatter on the network and if you make it too high, you
    may get latency spikes. Default value is 150.                         


