| /* |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| */ |
| |
| /** |
| * \file jrec.h |
| * |
| * Qpid asynchronous store plugin library |
| * |
| * File containing source code for class mrg::journal::jrec (abstract journal |
| * jrecord). See class documentation for details. |
| * |
| * \author Kim van der Riet |
| */ |
| |
| #ifndef QPID_LEGACYSTORE_JRNL_JREC_H |
| #define QPID_LEGACYSTORE_JRNL_JREC_H |
| |
| namespace mrg |
| { |
| namespace journal |
| { |
| class jrec; |
| } |
| } |
| |
| #include <cstddef> |
| #include <fstream> |
| #include "qpid/legacystore/jrnl/rec_hdr.h" |
| #include "qpid/legacystore/jrnl/rec_tail.h" |
| #include <string> |
| #include <sys/types.h> |
| |
| namespace mrg |
| { |
| namespace journal |
| { |
| |
| /** |
| * \class jrec |
| * \brief Abstract class for all file jrecords, both data and log. This class establishes |
| * the common data format and structure for these jrecords. |
| */ |
| class jrec |
| { |
| public: |
| jrec(); |
| virtual ~jrec(); |
| |
| /** |
| * \brief Encode this instance of jrec into the write buffer at the disk-block-aligned |
| * pointer wptr starting at position rec_offs_dblks in the encoded record to a |
| * maximum size of max_size_dblks. |
| * |
| * This call encodes the content of the data contianed in this instance of jrec into a |
| * disk-softblock-aligned (defined by JRNL_SBLK_SIZE) buffer pointed to by parameter |
| * wptr. No more than paramter max_size_dblks data-blocks may be written to the buffer. |
| * The parameter rec_offs_dblks is the offset in data-blocks within the fully encoded |
| * data block this instance represents at which to start encoding. |
| * |
| * Encoding entails writing the record header (struct enq_hdr), the data and the record tail |
| * (struct enq_tail). The record must be data-block-aligned (defined by JRNL_DBLK_SIZE), |
| * thus any remaining space in the final data-block is ignored; the returned value is the |
| * number of data-blocks consumed from the page by the encode action. Provided the initial |
| * alignment requirements are met, records may be of arbitrary size and may span multiple |
| * data-blocks, disk-blocks and/or pages. |
| * |
| * Since the record size in data-blocks is known, the general usage pattern is to call |
| * encode() as many times as is needed to fully encode the data. Each call to encode() |
| * will encode as much of the record as it can to what remains of the current page cache, |
| * and will return the number of data-blocks actually encoded. |
| * |
| * <b>Example:</b> Assume that record r1 was previously written to page 0, and that this |
| * is an instance representing record r2. Being larger than the page size ps, r2 would span |
| * multiple pages as follows: |
| * <pre> |
| * |<---ps--->| |
| * +----------+----------+----------+----... |
| * | |r2a| r2b | r2c | | |
| * |<-r1-><----------r2----------> | |
| * +----------+----------+----------+----... |
| * page: p0 p1 p2 |
| * </pre> |
| * Encoding record r2 will require multiple calls to encode; one for each page which |
| * is involved. Record r2 is divided logically into sections r2a, r2b and r2c at the |
| * points where the page boundaries intersect with the record. Assuming a page size |
| * of ps, the page boundary pointers are represented by their names p0, p1... and the |
| * sizes of the record segments are represented by their names r1, r2a, r2b..., the calls |
| * should be as follows: |
| * <pre> |
| * encode(p0+r1, 0, ps-r1); (returns r2a data-blocks) |
| * encode(p1, r2a, ps); (returns r2b data-blocks which equals ps) |
| * encode(p2, r2a+r2b, ps); (returns r2c data-blocks) |
| * </pre> |
| * |
| * \param wptr Data-block-aligned pointer to position in page buffer where encoding is to |
| * take place. |
| * \param rec_offs_dblks Offset in data-blocks within record from which to start encoding. |
| * \param max_size_dblks Maximum number of data-blocks to write to pointer wptr. |
| * \returns Number of data-blocks encoded. |
| */ |
| virtual u_int32_t encode(void* wptr, u_int32_t rec_offs_dblks, |
| u_int32_t max_size_dblks) = 0; |
| |
| /** |
| * \brief Decode into this instance of jrec from the read buffer at the disk-block-aligned |
| * pointer rptr starting at position jrec_offs_dblks in the encoded record to a |
| * maximum size of max_size_blks. |
| * |
| * This call decodes a record in the page buffer pointed to by the data-block-aligned |
| * (defined by JRNL_DBLK_SIZE) parameter rptr into this instance of jrec. No more than |
| * paramter max_size_dblks data-blocks may be read from the buffer. The parameter |
| * jrec_offs_dblks is the offset in data-blocks within the encoded record at which to start |
| * decoding. |
| * |
| * Decoding entails reading the record header, the data and the tail. The record is |
| * data-block-aligned (defined by JRNL_DBLK_SIZE); the returned value is the number of |
| * data-blocks read from the buffer by the decode action. As the record data size is only |
| * known once the header is read, the number of calls required to complete reading the |
| * record will depend on the vlaues within this instance which are set when the |
| * header is decoded. |
| * |
| * A non-zero value for jrec_offs_dblks implies that this is not the first call to |
| * decode and the record data will be appended at this offset. |
| * |
| * \param h Reference to instance of struct hdr, already read from page buffer and used |
| * to determine record type |
| * \param rptr Data-block-aligned pointer to position in page buffer where decoding is to |
| * begin. |
| * \param rec_offs_dblks Offset within record from which to start appending the decoded |
| * record. |
| * \param max_size_dblks Maximum number of data-blocks to read from pointer rptr. |
| * \returns Number of data-blocks read (consumed). |
| */ |
| virtual u_int32_t decode(rec_hdr& h, void* rptr, u_int32_t rec_offs_dblks, |
| u_int32_t max_size_dblks) = 0; |
| |
| virtual bool rcv_decode(rec_hdr h, std::ifstream* ifsp, std::size_t& rec_offs) = 0; |
| |
| virtual std::string& str(std::string& str) const = 0; |
| virtual std::size_t data_size() const = 0; |
| virtual std::size_t xid_size() const = 0; |
| virtual std::size_t rec_size() const = 0; |
| inline virtual u_int32_t rec_size_dblks() const { return size_dblks(rec_size()); } |
| static inline u_int32_t size_dblks(const std::size_t size) |
| { return size_blks(size, JRNL_DBLK_SIZE); } |
| static inline u_int32_t size_sblks(const std::size_t size) |
| { return size_blks(size, JRNL_DBLK_SIZE * JRNL_SBLK_SIZE); } |
| static inline u_int32_t size_blks(const std::size_t size, const std::size_t blksize) |
| { return (size + blksize - 1)/blksize; } |
| virtual u_int64_t rid() const = 0; |
| |
| protected: |
| virtual void chk_hdr() const = 0; |
| virtual void chk_hdr(u_int64_t rid) const = 0; |
| virtual void chk_tail() const = 0; |
| static void chk_hdr(const rec_hdr& hdr); |
| static void chk_rid(const rec_hdr& hdr, u_int64_t rid); |
| static void chk_tail(const rec_tail& tail, const rec_hdr& hdr); |
| virtual void clean() = 0; |
| }; // class jrec |
| |
| } // namespace journal |
| } // namespace mrg |
| |
| #endif // ifndef QPID_LEGACYSTORE_JRNL_JREC_H |
