/home/serif/byzantine_generals/src/mailbox.h

Go to the documentation of this file.

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

#ifndef SRC_MAILBOX_H_
#define SRC_MAILBOX_H_

#include <boost/interprocess/sync/interprocess_semaphore.hpp>
#include <boost/interprocess/allocators/allocator.hpp>

#include "orderqueue.h"

/**
 * @brief  Plain Old Data (POD) container for a General's end point of
 * communication.  Each general owns exactly one Mailbox, where other
 * Generals can place Orders bound for the owning general.  The owning
 * general only reads from the contained @ref OrderQueue, while other
 * generals only write to the contained @ref OrderQueue.  In this way,
 * the @ref OrderQueue models a multi-producer, single-consumer problem.
 */
struct Mailbox {
    /**
     * @brief  The owning Lieutenant General waits on this semaphore to
     * be non-zero (always in the range of [0, 1]), which indicates that
     * a single round's work can commence.  It is easiest to think of this in
     * terms of "this semaphore tracks the number of rounds the owning general
     * may perform."
     */
    boost::interprocess::interprocess_semaphore sem_round_empty;

    /**
     * @brief  The single Commanding General waits on this semaphore to be
     * non-zero (always in the range of [0, 1]), which indicates that the
     * owning Lieutenant General has completed the current round.  It is easiest
     * to think of this in terms of "this semaphore tracks the number of rounds
     * the owning general just completed."
     */
    boost::interprocess::interprocess_semaphore sem_round_fill;

    /**
     * @brief  The queue that stores transfer of ownership over Orders between
     * the writer (non-owning general) and reader (owning general).  The Queue
     * operates as standard Queues do, in that its FIFO, where the first
     * contained @ref Order is the oldest and the last @ref Order is the newest.
     * Enqueue occurs at the back, dequeue from the front.
     */
    OrderQueue orders;

    /**
     * @brief Constructor.  Our initialization list instantiates @ref
     * sem_round_empty to 0 and @ref sem_round_fill to 0 to indicate that the 
     * owning Lieutenant General needs to wait on the Communication General 
     * to begin.
     *
     * @param order_alloc The shared memory allocator that our @ref orders
     * should use when allocating an @ref Order.
     */
    explicit Mailbox(const OrderAllocator &order_alloc):
        sem_round_empty(0),
        sem_round_fill(0),
        orders(order_alloc) {
    }

    /**
     * @brief  Destructor
     */
    ~Mailbox() {
        /* Safety check that we've processed all of the orders in this
         * mailbox */
        assert(orders.Empty() == true);
    }
};

#endif  // SRC_MAILBOX_H_

---