/home/serif/byzantine_generals/src/order.h

Go to the documentation of this file.

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

#ifndef SRC_ORDER_H_
#define SRC_ORDER_H_

#include <boost/shared_ptr.hpp>

#include "sharedmemtypes.h"

/**
 * @brief  The types of Marching Orders that may be passed amongst
 * the Generals.  We wrap in a namespace here to avoid polluting
 * the global namespace and to help avoid name collisions.
 */
namespace MarchingOrders {
    /**
     * @brief  See @ref MarchingOrders
     */
    enum type {
        kInvalid = 0,/*!< Invalid order */
        kAttack,  /*!< Attack city */
        kRetreat,  /*!< Retreat from battlefield */
    };
};

/**
 * @brief  This represents the basic message that is passed around
 * amongst the generals during operation.  Each receiving general
 * (regardless of loyalty) is obligated to append their Unique ID to
 * the enclosed @ref communication_path.  A Loyal General will never
 * modify the enclosed @ref marching_orders, while Disloyal Generals
 * may to cause as much confusion as possible.
 */
class Order {
    public:

        /**
         * @brief  A list of Generals' Unique IDs whom have seen this Order.
         * The first entry was the General who created this Order, and
         * the last entry is the currently owning General.  All Generals
         * who receive this Order are required to append their Unique ID
         * to the list, preferably using @ref AppendCommPathEntry.
         */
        SharedMemoryUIntList communication_path;

        /**
         * @brief  The relayed Order.
         */
        MarchingOrders::type marching_orders;

        /**
         * @brief  Constructor
         *
         * @param alloc  The allocator to use in the underlying @ref
         * communication_path
         * @param march_orders The initial marching orders to carry
         */
        Order(const SharedMemoryUIntAllocator &alloc,
              MarchingOrders::type march_orders = MarchingOrders::kInvalid);

        /**
         * @brief  Copy Constructor
         *
         * @param o Order to copy
         */
        Order(const Order& o);

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

        /**
         * @brief  Helper function to convert a marching order to a human
         * readable string.  For example, MarchingOrders::kAttack will get
         * converted to "Attack". This same paradigm applies to both "Retreat"
         * and "Invalid".
         *
         * @param marching_order Marching order to convert
         *
         * @return  Human friendly converted string
         */
        static boost::interprocess::string
            MarchingOrderTypeToString(MarchingOrders::type marching_order);

        /**
         * @brief  Helper function to add a general's unique ID to the @ref
         * communication_path
         *
         * @param kUniqueID General's Unique ID
         */
        void AppendCommPathEntry(const unsigned int kUniqueID);

        /**
         * @brief  Convert the enclosed communication path to a human
         * readable string where unique IDs are delimited by a space.
         * For example, if the communication path contains the General
         * IDs 0 and 1, the output of this function would be "0 1".
         *
         * @return  Communication path as a string
         */
        boost::interprocess::string CommunicationPathToString() const;
};

/**
 * @brief  Type for a Shared pointer which wraps an @ref Order
 */
typedef boost::shared_ptr<Order> LocalOrder;

#endif  // SRC_ORDER_H_

---