6.3. Configuring the Journal

MRG Messaging allows the size and number of files and caches used for persistence to be configured. There is one journal for each queue; it records each enqueue, dequeue, or transaction event, in order.
Each journal is implemented as a circular queue on disk, with a read cache and a write cache in memory. On disk, each circular queue consists of a set of files. The caches are page-oriented. When persistent messages are written to a durable queue, the associated events accumulate in the write cache until a page is filled or a timeout occurs, then the page is written to the circular queue using AIO. Messages in the write cache have not yet been acknowledged to the publisher, and can not be read by a consumer until they have been written to the journal. The page size affects performance—smaller page sizes reduce latency, larger page sizes reduce throughput by reducing the number of write operations.
The journal files are prepared and formatted when the associated queue is first declared. This doubles throughput with AIO on the first pass, and also guarantees that needed space is allocated. However, this can result in a noticeable delay when durable queues are declared. When file size is increased, the delay is greater.

Important

Because the size of a circular queue is fixed, it is important to make journals large enough to contain the maximum number of messages anticipated. If the journal becomes approximately 80% full, no new messages can be enqueued, and an attempt to enqueue further messages results in an enqueue threshold exception (RHM_IORES_ENQCAPTHRESH). Dequeues are still allowed, and each dequeue frees up space in the store, so enqueues can continue once sufficient space has been freed.
Because transactions can span many persistent queues, enqueue and dequeue events within a transaction are placed in a dedicated persistent queue called the TPL (Transaction Prepared List). When a transaction is committed, the associated events are written to the journal before the transaction commit is acknowledged to the message consumer and messages published in the transaction are made available to message consumers.
When you create a queue using qpid-config, you can set the size of the journal using the --file-count and --file-size options.
In C++, you can set the file count and file size by specifying qpid.file_size and qpid_file_count in Session.createQueue():
FieldTable journal_settings;
journal_settings.setInt("qpid.file_size", 20);
journal_settings.setInt("qpid.file_count", 12);

session.queueDeclare(arg::queue="my_queue", arg::durable=true, arg::arguments=journal_settings);
In Python, you can set the file count and file size by specifying qpid.file_size and qpid.file_count in session.queue_declare():
session.queue_declare(queue="my_queue", durable=True, arguments={"qpid.file_size":20, "qpid.file_count":12})
The following table lists the options that can be set for persistence when starting the MRG Messaging broker.

Table 6.1. Persistence Options

Persistence Options
--store-dir DIRECTORY The directory for journals and persistent configuration. The default is /var/lib/qpidd when run as a daemon, or ~/.qpidd when run from the command line.
--num-jfiles NUMBER The number of files for each instance of the persistence journal. The default is 8. Minimum is 4, maximum is 64. The total size of each journal is num-jfiles * jfile-size-pgs.
--jfile-size-pgs NUMBER The size of each journal file, in multiples of 64KB. The default is 24. Minimum is 1, maximum is 32768. The total size of each journal is num-jfiles * jfile-size-pgs. The default size for a journal is 1.5 megabytes. The minimum size is 64 kilobytes, the maximum size is 2 gigabytes
--wcache-page-size NUMBER The size (in KB) of the pages in the write page cache. Allowable values must be powers of 2 (1, 2, 4, ... 128). Lower values will decrease latency but also decrease throughput. The default is 32.
--tpl-num-jfiles NUMBER The number of files for each instance of the TPL journal. The default is 8. Minimum is 4, maximum is 64.
--tpl-jfile-size-pgs NUMBER The size of each TPL journal file in multiples of 64KB. The default is 24. Minimum is 1, maximum is 32768.
--tpl-wcache-page-size NUMBER The size (in KB) of the pages in the TPL write page cache. Allowable values must be powers of 2 (1, 2, 4, ... 128). Lower values will decrease latency but also decrease throughput. The default is 32.
--truncate yes|no If yes, truncates the store, discarding any existing records. If no, preserves any existing stores for recovery.

Correcting Illegal Numeric Parameters

If an out-of-range or illegal parameter is supplied to the store, it will automatically replace it with the closest legal value and place a warning in the log file rather than fail. This applies to all numeric store parameters.
For example, starting the store with --num-jfiles 1 (which is out-of-range, the minimum allowed is 4), the store will automatically substitute a value of 4 and place the following warning into the log file: "warning parameter num-jfiles (1) is below allowable minimum (4); changing this parameter to minimum value."
Similarly, if a value which is not a power of 2 is given for the wcache-page-size parameter, the closest power of 2 will be substituted with a warning in the log file.