/home/serif/byzantine_generals/src/byzantinegeneralthread.h

Go to the documentation of this file.

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

#ifndef SRC_BYZANTINEGENERALTHREAD_H_
#define SRC_BYZANTINEGENERALTHREAD_H_

#include <boost/thread/thread.hpp>
#include <boost/shared_ptr.hpp>
#include <boost/interprocess/managed_shared_memory.hpp>

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

#include "order.h"
#include "ordertree.h"
#include "sharedmemtypes.h"

/**
 * @brief Every instance of this class operates as a thread, in one of two
 * operational modes:
 *
 * 1. Commanding General - Kick off initial order to Lieutenant Generals,
 * and control when each of the Lieutenant Generals are allowed to begin their
 * rounds of communication.
 *
 * 2. Lieutenant General - Wait for orders from other generals, generate
 * orders to other generals, and coordinate with the Commanding General for
 * when messages may be sent or received (rounds).  Upon reception of a
 * message (aka Order), this general will append his unique ID to the
 * received message and queue broadcasting that message to all other generals.
 * Prior to beginning each round, and upon completion of each round, this
 * thread will coordinate with the Commanding General thread to begin
 * subsequent rounds.
 */
class ByzantineGeneralThread {
    public:
        /**
         * @brief Create a thread that represents a single byzantine general,
         * eiher in Commanding General mode or in Lieutenant Genearl mode.
         *
         * @param kUniqueID Unique Identifier for this thread.  When 0, this
         * thread will be the commanding general.  When > 0, this thread will be
         * a Lieutenant General.
         *
         * @param kSharedMemName The shared memory area's name.
         *
         * @param kMailboxVectorName The name of the mailbox vector within the
         * shared memory area.
         *
         * @param kIsLoyal TRUE if this general is set to loyal, FALSE if
         * disloyal
         *
         * @param kTotalNumberGenerals The total number of generals involved in
         * this problem
         *
         * @param kTotalNumberMessages The total number of messages this general
         * should expect to receive during his lifetime.
         *
         * @param kBroadcastRoundsRequired The number of rounds this general
         * should broadcast for.
         *
         * @param kLogCategoryName The name of the logging category to use for
         * output.
         *
         * @param kGenerateGraph TRUE if this general should generate a DOT
         * output graph from the tree of received messages, FALSE otherwise.
         *
         * @param kTraitorSetName The set in which the unique identifiers of all
         * of the traitors are stored.
         */
        ByzantineGeneralThread(const unsigned int kUniqueID,
                               const char* kSharedMemName,
                               const char* kMailboxVectorName,
                               const bool kIsLoyal,
                               const unsigned int kTotalNumberGenerals,
                               const unsigned int kTotalNumberMessages,
                               const unsigned int kBroadcastRoundsRequired,
                               const char* kLogCategoryName,
                               const bool kGenerateGraph,
                               const char* kTraitorSetName);

        /**
         * @brief  Destructor
         */
        ~ByzantineGeneralThread(void);

        /**
         * @brief  Request that this thread stop
         */
        void Stop();

        /**
         * @brief  Create and run this thread
         */
        void Start();

    private:

        /**
         * @brief  List of orders that are generated within this instance
         */
        typedef std::list<LocalOrder> LocalOrderList;

        /**
         * @brief  This general's unique identifer (ID).  The Commanding General
         * is always 0, while the Lieutenant Generals are always > 0.
         */
        const unsigned int kUniqueID_;

        /**
         * @brief  TRUE if this General is loyal, FALSE otherwise.  A loyal
         * general will pass orders through unmolested, while a disloyal general
         * will randomly corrupt orders passed through.
         */
        const bool kIsLoyal_;

        /**
         * @brief  The total number of generals on the battlefield.
         */
        const unsigned int kTotalNumberGenerals_;

        /**
         * @brief  The total number of messages this general is expected to
         * receive during his lifetime.
         */
        const unsigned int kTotalNumberMessages_;

        /**
         * @brief  The number of rounds to broadcast orders.  Each round
         * consists of receiving an order, appending my unique id, and queueing
         * that order for transmission to the other generals during the next
         * round.
         */
        const unsigned int kBroadcastRoundsRequired_;

        /**
         * @brief  TRUE to generate a DOT graph of the received messages, FALSE
         * otherwise.
         */
        const bool kGenerateGraph_;

        /**
         * @brief  Begin executing this thread.
         */
        void Run();

        /**
         * @brief  Broadcast all queued orders from the previous round.
         */
        void BroadcastOrders();

        /**
         * @brief  The Lieutenant General operational mode's run routine.
         */
        void LieutenantGeneralRun();

        /**
         * @brief  The Commanding General operational mode's run routine.
         */
        void CommandingGeneralRun();

        /**
         * @brief  This instance's thread information
         */
        boost::shared_ptr<boost::thread> thread_;

        /**
         * @brief  Shared memory segment reference.  We communicate to the
         * other generals via this shared memory region.
         */
        boost::interprocess::managed_shared_memory* segment_;

        /**
         * @brief  The Tree of received orders.  Each received order's
         * communication path is used to determine its placement in the tree.
         * The Commanding Generals' initial order is always the root node.  The
         * set of all nodes at a given depth (level) represent all of the
         * messages received in that round of communication.
         */
        OrderTree* received_orders_;

        /**
         * @brief  Shared memory region's vector of mailboxes.  Each mailbox
         * belongs to a single General where the index into the vector is the
         * owning General's Unique ID (@ref kUniqueID_).  Other generals can
         * queue messages for the owning general by placing Orders for that
         * general into his mailbox.  The owning general will read orders out of
         * his mailbox during rounds.
         */
        SharedMemoryMailboxVector* mailbox_vector_;

        /**
         * @brief  The list of orders we want to transmit at the beginning of
         * the next round.
         */
        LocalOrderList order_transmit_queue_;

        /**
         * @brief  Debug logger reference
         */
        log4cpp::Category& log_;

        /**
         * @brief  Seed used in random number generator
         */
        unsigned int rand_seed_;
};

#endif  // SRC_BYZANTINEGENERALTHREAD_H_

---