/home/serif/byzantine_generals/src/clihandler.h

Go to the documentation of this file.

/**
 * @file clihandler.h
 * @author Reshen Amin <reshen@zensrc.com>
 *
 * @brief Contains the class definition for kicking off the program
 *
 * @license Byzantine Generals Problem Coding Sample.<br>
 * Copyright (C) 2010  Reshen Amin.<br>
 * See @ref license_sec for details.<br>
 */

#ifndef SRC_CLIHANDLER_H_
#define SRC_CLIHANDLER_H_

#include <boost/interprocess/managed_shared_memory.hpp>

#include <log4cpp/Category.hh>
#include <vector>

#include "sharedmemtypes.h"

/**
 * @brief  Main's potential return codes on program exit
 */
namespace ByzGeneralsReturnCodes {
    /**
     * @brief  See @ref ByzGeneralsReturnCodes
     */
    enum type {
        kNoError = 0,  /*!< No Error, execution completed fine. */
        kHelpExitNoError,  /*!< No Error, User asked for usage help. */
        kInvalidInput,  /*!< Invalid command line arguments received */
        kIPCError,  /*!< Interprocess Communication (IPC) Error */
        kUnknown  /*!< Unknown Error/Exception occured */
    };
};

class ByzantineGeneralThread;

/**
 * @brief  This class is responsible for providing an execution harness into
 * the Byzantine Generals coding sample.  It is intended to be called directly
 * from main().
 */
class CLIHandler {
    public:
        /**
         * @brief  Constructor
         */
        CLIHandler();

        /**
         * @brief  Destructor
         */
        ~CLIHandler();

        /**
         * @brief  Begin execution of the Byzantine General coding sample.  This
         * function will not return until all of the threads which are created
         * are completed.
         *
         * @param argc Command Line argument count
         * @param argv Command Line argument values
         *
         * @return  The result of parsing arguments and creating/executing of
         * the threads
         */
        ByzGeneralsReturnCodes::type Exec(int argc, char* argv[]);


    private:
        /**
         * @brief  Shared memory region name.  This is the unique identifier
         * used to find the region of memory shared between the various
         * Byzantine General Threads. All shared objects are stored in this
         * region.
         */
        static const char* kSharedMemoryName_;

        /**
         * @brief  Mailbox vector (in shared memory) name.  See @ref Mailbox
         * for details on what each @ref Mailbox is used for.
         */
        static const char* kMailboxVectorName_;

        /**
         * @brief  Traitor set (in shared memory) name.  This is a simple set
         * used to track the Generals who are created as traitors.
         */
        static const char* kTraitorSetName_;

        /**
         * @brief  Logging category name
         */
        static const char* kLogCategoryName_;

        /**
         * @brief  Maximum size of shared memory region in bytes.  We pick a
         * maximum memory area size sufficiently large to allow testing of up to
         * 4 traitors and 9 loyalists.  This value can be increased arbitrairly
         * to test larger cases
         */
        static const int kSharedMemoryMaxSize_ = 50000000;

        /**
         * @brief  Logging endpoint
         */
        log4cpp::Category& log_;

        /**
         * @brief  Create a logging endpoint
         *
         * @return   Logging endpoint reference
         */
        log4cpp::Category& InitializeLogger();

        /**
         * @brief  Parse and validate command line arguments (CLI)
         *
         * @param argc Command Line argument count
         * @param argv Command Line argument values
         *
         * @return  Status of argument parsing
         */
        ByzGeneralsReturnCodes::type ParseAndValidateArguments(int argc,
                                                               char* argv[]);

        /**
         * @brief  Create the Byzantine General Threads.  This function will
         * store created thread references into @ref byzantine_generals_
         */
        void CreateGeneralThreads();

        /**
         * @brief  Destroy Byzantine General Threads.  This function will
         * destroy any thread references stored in @ref byzantine_generals_
         * Threads should be completed prior to calling this function.
         */
        void DestroyGeneralThreads();

        /**
         * @brief  Calculate the number of orders each general should expect
         * and the total number of rounds that those orders will be sent across.
         */
        void CalculateOrdersAndRounds();

        /**
         * @brief  Create shared memory region and the data structures within
         * the shared memory region (Traitor Set, Mailbox Vector, etc..)
         */
        void CreateSharedMemoryItems();

        /**
         * @brief  Destroy the shared memory region and all of its contents
         */
        void DestroySharedMemoryItems();

        /**
         * @brief  The number of rounds that communication will take place over.
         * This is always m + 1, where m is the number of traitors the user
         * specified.
         */
        unsigned int number_rounds_;

        /**
         * @brief  User specified number of traitor (disloyal) generals
         */
        unsigned int number_traitor_generals_;

        /**
         * @brief  User specified number of loyal generals
         */
        unsigned int number_loyal_generals_;

        /**
         * @brief  User specified generation of DOT graphs, TRUE to generate
         * graphs, FALSE otherwise.
         */
        bool generate_dot_graph_;

        /**
         * @brief  Calculated total number of general (always equal to the
         * number of loyal generals + number of disloyal generals).
         */
        unsigned int total_number_generals_;

        /**
         * @brief  Calculated total number of messages that each Lieutenant
         * General should expect to receive.
         */
        unsigned int total_messages_per_lt_general_;

        /**
         * @brief  This vector stores references to the created Byzantine
         * General Threads.  It is populated by @ref CreateGeneralThreads and
         * cleared by @ref DestroyGeneralThreads
         */
        std::vector<ByzantineGeneralThread *> byzantine_generals_;

        /**
         * @brief  Reference to the created shared memory region.  It is
         * populated by @ref CreateSharedMemoryItems and destroyed by @ref
         * DestroySharedMemoryItems
         */
        boost::interprocess::managed_shared_memory* segment_;

        /**
         * @brief  This set, which is stored in shared memory, keeps track of
         * the unique identifiers of each of the disloyal Byzantine General
         * Threads. It is populated by @ref CreateSharedMemoryItems and
         * destroyed by @ref DestroySharedMemoryItems
         */
        SharedMemoryUIntSet* traitor_set_;

        /**
         * @brief  This vector stores the mailboxes for each of the Generals.
         * See @ref Mailbox for details.  It is populated by @ref
         * CreateSharedMemoryItems and destroyed by @ref
         * DestroySharedMemoryItems
         */
        SharedMemoryMailboxVector* mailbox_vector_;
};

#endif  // SRC_CLIHANDLER_H_

---