Bug 673225

Please provide further information for documentation.

LKB

I don't know what these are? I am simply trying to go through the documentation and came across this portion in the examples, and there was no explanation.

Gordon,

Are you able to help out with source documentation?

LKB

The 'rec hdr and tail' is the combination of 'enqueue header size' and 'enqueue  record tail' defined in the text preceding the example. I'd suggest to change the line in the example from:

An average enqueue record will consume 150 (msg) + 75 (msg header) + 44 (rec hdr and tail) = 269 bytes.

to:

An average enqueue record will consume 32 (enqueue header size) + 150 (msg) + 75 (msg header) + 12 (enqueue record tail) = 269 bytes. 

Even better would perhaps be to change 'enqueue header size' to 'enqueue record header' for consistency, both in the example and in the preceding text.

Any comments, Kim?

This seems fine to me.

The journal uses records to store data. If the record contains data (such as enqueue records), then the record consists of a record header and a record tail, with the data sandwiched between these two. Any space remaining between the end of the tail and the next 128-byte boundary remains unused; the next journal record will start on this boundary.

The user data supplied to the journal from the broker comes in two parts, a message header and the message data itself. The journal, however, treats both of these as a single block of opaque binary data.

128-byte                                     128 byte
boundary                                     boundary
   |                                            |
---+-----+------------------------+-----+-------+---
   | rec |           user         | rec | extra |    
   | hdr |           data         | tail| space |    
---+-----+------------------------+-----+-------+--- 
         |                        |
        /                          \
       /                            \
      |                              |
      +-----+------------------------+
      | msg |         message        |    Broker's view of
      | hdr |          data          |    the user data
      +-----+------------------------+

For the size calculations, the journal's record header and record tail are fixed in size, being 32 bytes and 12 bytes respectively (total: 44 bytes). The broker's user data size is variable, and examples must state exactly how big the message header and message data portion of the user data will be (in the example above, 75 bytes for the header and 150 bytes for the message data).