path: root/cpp/src/qpid/legacystore/jrnl/lpmgr.h

/*
 *
 * 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 lpmgr.h
 *
 * Qpid asynchronous store plugin library
 *
 * Class mrg::journal::lpmgr. See class documentation for details.
 *
 * \author Kim van der Riet
 */

#ifndef QPID_LEGACYSTORE_JRNL_LPMGR_H
#define QPID_LEGACYSTORE_JRNL_LPMGR_H

namespace mrg
{
namespace journal
{
    class jcntl;
    class lpmgr;
}
}

#include "qpid/legacystore/jrnl/fcntl.h"
#include <vector>

namespace mrg
{
namespace journal
{

    /**
    * \brief LFID-PFID manager. This class maps the logical file id (lfid) to the physical file id (pfid) so that files
    * may be inserted into the file ring buffer in (nearly) arbitrary logical locations while the physical ids continue
    * to be appended. NOTE: NOT THREAD SAFE.
    *
    * The entire functionality of the LFID-PFID manager is to maintain an array of pointers to fcntl objects which have
    * a one-to-one relationship to the physical %journal files. The logical file id (lfid) is used as an index to the
    * array to read the mapped physical file id (pfid). By altering the order of these pointers within the array, the
    * mapping of logical to physical files may be altered. This can be used to allow for the logical insertion of
    * %journal files into a ring buffer, even though the physical file ids must be appended to those that preceded them.
    *
    * Since the insert() operation uses after-lfid as its position parameter, it is not possible to insert before lfid
    * 0 - i.e. It is only possible to insert after an existing lfid. Consequently, lfid 0 and pfid 0 are always
    * coincident in a %journal. Note, however, that inserting before lfid 0 is logically equivilent to inserting after
    * the last lfid.
    *
    * When one or more files are inserted after a particular lfid, the lfids of the following files are incremented. The
    * pfids of the inserted files follow those of all existing files, thus leading to a lfid-pfid discreppancy (ie no
    * longer a one-to-one mapping):
    *
    * Example: Before insertion, %journal file headers would look as follows:
    * <pre>
    *          Logical view (sorted by lfid):               Physical view (sorted by pfid):
    *          +---+---+---+---+---+---+                    +---+---+---+---+---+---+
    * pfid --> | 0 | 1 | 2 | 3 | 4 | 5 |           pfid --> | 0 | 1 | 2 | 3 | 4 | 5 |
    * lfid --> | 0 | 1 | 2 | 3 | 4 | 5 |           lfid --> | 0 | 1 | 2 | 3 | 4 | 5 |
    *          +---+---+---+---+---+---+                    +---+---+---+---+---+---+
    * </pre>
    *
    * After insertion of 2 files after lid 2 (marked with *s):
    * <pre>
    *          Logical view (sorted by lfid):               Physical view (sorted by pfid):
    *          +---+---+---+---+---+---+---+---+            +---+---+---+---+---+---+---+---+
    * pfid --> | 0 | 1 | 2 |*6*|*7*| 3 | 4 | 5 |   pfid --> | 0 | 1 | 2 | 3 | 4 | 5 |*6*|*7*|
    * lfid --> | 0 | 1 | 2 |*3*|*4*| 5 | 6 | 7 |   lfid --> | 0 | 1 | 2 | 5 | 6 | 7 |*3*|*4*|
    *          +---+---+---+---+---+---+---+---+            +---+---+---+---+---+---+---+---+
    * </pre>
    *
    * The insert() function updates the internal map immediately, but the physical files (which have both the pfid and
    * lfid written into the file header) are only updated as they are overwritten in the normal course of enqueueing
    * and dequeueing messages. If the %journal should fail after insertion but before the files following those inserted
    * are overwritten, then duplicate lfids will be present (though no duplicate pfids are possible). The overwrite
    * indicator (owi) flag and the pfid numbers may be used to resolve the ambiguity and determine the logically earlier
    * lfid in this case.
    *
    * Example: Before insertion, the current active write file being lfid/pfid 2 as determined by the owi flag, %journal
    * file headers would look as follows:
    * <pre>
    *          Logical view (sorted by lfid):               Physical view (sorted by pfid):
    *          +---+---+---+---+---+---+                    +---+---+---+---+---+---+
    * pfid --> | 0 | 1 | 2 | 3 | 4 | 5 |           pfid --> | 0 | 1 | 2 | 3 | 4 | 5 |
    * lfid --> | 0 | 1 | 2 | 3 | 4 | 5 |           lfid --> | 0 | 1 | 2 | 3 | 4 | 5 |
    *  owi --> | t | t | t | f | f | f |            owi --> | t | t | t | f | f | f |
    *          +---+---+---+---+---+---+                    +---+---+---+---+---+---+
    * </pre>
    *
    * After inserting 2 files after lfid 2 and then 3 (the newly inserted file) - marked with *s:
    * <pre>
    *          Logical view (sorted by lfid):               Physical view (sorted by pfid):
    *          +---+---+---+---+---+---+---+---+            +---+---+---+---+---+---+---+---+
    * pfid --> | 0 | 1 | 2 |*6*|*7*| 3 | 4 | 5 |   pfid --> | 0 | 1 | 2 | 3 | 4 | 5 |*3*|*4*|
    * lfid --> | 0 | 1 | 2 |*3*|*4*| 3 | 4 | 5 |   lfid --> | 0 | 1 | 2 | 3 | 4 | 5 |*3*|*4*|
    *  owi --> | t | t | t | t | t | f | f | f |    owi --> | t | t | t | f | f | f | t | t |
    *          +---+---+---+---+---+---+---+---+            +---+---+---+---+---+---+---+---+
    * </pre>
    *
    * If a broker failure occurs at this point, then there are two independent tests that may be made to resolve
    * duplicate lfids during recovery in such cases:
    * <ol>
    *   <li>The correct lfid has owi flag that matches that of pfid/lfid 0</li>
    *   <li>The most recently inserted (hence correct) lfid has pfids that are higher than the duplicate that was not
    *       overwritten</li>
    * </ol>
    *
    * NOTE: NOT THREAD SAFE. Provide external thread protection if used in multi-threaded environments.
    */
    class lpmgr
    {
    public:
        /**
        * \brief Function pointer to function that will create a new fcntl object and return its pointer.
        *
        * \param jcp        Pointer to jcntl instance from which journal file details will be obtained.
        * \param lfid       Logical file ID for new fcntl instance.
        * \param pfid       Physical file ID for file associated with new fcntl instance.
        * \param rdp        Pointer to rcvdat instance which conatins recovery information for new fcntl instance when
        *                   recovering an existing file, or null if a new file is to be created.
        */
        typedef fcntl* (new_obj_fn_ptr)(jcntl* const jcp,
                                        const u_int16_t lfid,
                                        const u_int16_t pfid,
                                        const rcvdat* const rdp);

    private:
        bool _ae;                       ///< Auto-expand mode
        u_int16_t _ae_max_jfiles;       ///< Max file count for auto-expansion; 0 = no limit
        std::vector<fcntl*> _fcntl_arr; ///< Array of pointers to fcntl objects

    public:
        lpmgr();
        virtual ~lpmgr();

        /**
        * \brief Initialize from scratch for a known number of %journal files. All lfid values are identical to pfid
        * values (which is normal before any inserts have occurred).
        *
        * \param num_jfiles Number of files to be created, and consequently the number of fcntl objects in array
        *                   _fcntl_arr.
        * \param ae         If true, allows auto-expansion; if false, disables auto-expansion.
        * \param ae_max_jfiles The maximum number of files allowed for auto-expansion. Cannot be lower than the current
        *                   number of files. However, a zero value disables the limit checks, and allows unlimited
        *                   expansion.
        * \param jcp        Pointer to jcntl instance. This is used to find the file path and base filename so that
        *                   new files may be created.
        * \param fp         Pointer to function which creates and returns a pointer to a new fcntl object (and hence
        *                   causes a new %journal file to be created).
        */
        void initialize(const u_int16_t num_jfiles,
                        const bool ae,
                        const u_int16_t ae_max_jfiles,
                        jcntl* const jcp,
                        new_obj_fn_ptr fp);

        /**
        * \brief Initialize from a known lfid-pfid map pfid_list (within rcvdat param rd), which is usually obtained
        * from a recover. The index of pfid_list is the logical file id (lfid); the value contained in the vector is
        * the physical file id (pfid).
        *
        * \param rd         Ref to rcvdat struct which contains recovery data and the pfid_list.
        * \param jcp        Pointer to jcntl instance. This is used to find the file path and base filename so that
        *                   new files may be created.
        * \param fp         Pointer to function which creates and returns a pointer to a new fcntl object (and hence
        *                   causes a new %journal file to be created).
        */
        void recover(const rcvdat& rd,
                     jcntl* const jcp,
                     new_obj_fn_ptr fp);

        /**
        * \brief Insert num_jfiles files after lfid index after_lfid. This causes all lfids after after_lfid to be
        * increased by num_jfiles.
        *
        * Note that it is not possible to insert <i>before</i> lfid 0, and thus lfid 0 should always point to pfid 0.
        * Inserting before lfid 0 is logically equivilent to inserting after the last lfid in a circular buffer.
        *
        * \param after_lfid Lid index after which to insert file(s).
        * \param jcp        Pointer to jcntl instance. This is used to find the file path and base filename so that
        *                   new files may be created.
        * \param fp         Pointer to function which creates and returns a pointer to a new fcntl object (and hence
        *                   causes a new %journal file to be created).
        * \param num_jfiles The number of files by which to increase.
        */
        void insert(const u_int16_t after_lfid,
                    jcntl* const jcp,
                    new_obj_fn_ptr fp,
                    const u_int16_t num_jfiles = 1);

        /**
        * \brief Clears _fcntl_arr and deletes all fcntl instances.
        */
        void finalize();

        /**
        * \brief Returns true if initialized; false otherwise. After construction, will return false until initialize()
        * is called; thereafter true until finalize() is called, whereupon it will return false again.
        *
        * \return True if initialized; false otherwise.
        */
        inline bool is_init() const { return _fcntl_arr.size() > 0; }

        /**
        * \brief Returns true if auto-expand mode is enabled; false if not.
        *
        * \return True if auto-expand mode is enabled; false if not.
        */
        inline bool is_ae() const { return _ae; }

        /**
        * \brief Sets the auto-expand mode to enabled if ae is true, to disabled otherwise. The value of _ae_max_jfiles
        * must be valid to succeed (i.e. _ae_max_jfiles must be greater than the current number of files or be zero).
        *
        * \param ae         If true will enable auto-expand mode; if false will disable it.
        */
        void set_ae(const bool ae);

        /**
        * \brief Returns the number of %journal files, including any that were appended or inserted since
        * initialization.
        *
        * \return Number of %journal files if initialized; 0 otherwise.
        */
        inline u_int16_t num_jfiles() const { return static_cast<u_int16_t>(_fcntl_arr.size()); }

        /**
        * \brief Returns the maximum number of files allowed for auto-expansion.
        *
        * \return Maximum number of files allowed for auto-expansion. A zero value represents a disabled limit
        *   - i.e. unlimited expansion.
        */
        inline u_int16_t ae_max_jfiles() const { return _ae_max_jfiles; }

        /**
        * \brief Sets the maximum number of files allowed for auto-expansion. A zero value disables the limit.
        *
        * \param ae_max_jfiles The maximum number of files allowed for auto-expansion. Cannot be lower than the current
        *                   number of files. However, a zero value disables the limit checks, and allows unlimited
        *                   expansion.
        */
        void set_ae_max_jfiles(const u_int16_t ae_max_jfiles);

        /**
        * \brief Calculates the number of future files available for auto-expansion.
        *
        * \return The number of future files available for auto-expansion.
        */
        u_int16_t ae_jfiles_rem() const;

        /**
        * \brief Get a pointer to fcntl instance for a given lfid.
        *
        * \return Pointer to fcntl object corresponding to logical file id lfid, or 0 if lfid is out of range
        *   (greater than number of files in use).
        */
        inline fcntl* get_fcntlp(const u_int16_t lfid) const
                { if (lfid >= _fcntl_arr.size()) return 0; return _fcntl_arr[lfid]; }

        // Testing functions
        void get_pfid_list(std::vector<u_int16_t>& pfid_list) const;
        void get_lfid_list(std::vector<u_int16_t>& lfid_list) const;

    protected:

        /**
        * \brief Append num_jfiles files to the end of the logical and file id sequence. This is similar to extending
        * the from-scratch initialization.
        *
        * \param jcp        Pointer to jcntl instance. This is used to find the file path and base filename so that
        *                   new files may be created.
        * \param fp         Pointer to function which creates and returns a pointer to a new fcntl object (and hence
        *                   causes a new %journal file to be created).
        * \param num_jfiles The number of files by which to increase.
        */
        void append(jcntl* const jcp,
                    new_obj_fn_ptr fp,
                    const u_int16_t num_jfiles = 1);

    };

} // namespace journal
} // namespace mrg

#endif // ifndef QPID_LEGACYSTORE_JRNL_LPMGR_H