netrq.h

Go to the documentation of this file.

/*
 * netrq.h
 *
 * Copyright (c) 2009 Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Simple library for handling network request queues.
 */

#ifndef WAVEPACKET_NETRQ_H__
#define WAVEPACKET_NETRQ_H__


// includes --------------------------------------------------------------------
#include "xdrbuf/xdrbuf.h"              // depends on XDR buffer library

#include "threadsafe/smart_ptr.h"


namespace netrq {

// doxygen block

/// \ingroup networking
/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup netrq Network Request Queue
///
/// \n
/// A network request queue.  Clients can add requests with an ID and priority.
/// Later, clients can pull the most immediate requests from the queue,
/// and that request will be backed off.  Finally, clients can remove requests
/// altogether.
///
/// The client must construct IDs on its own.
///
/// This library makes use of a "clock".  In the context of a network request
/// queue, this is just a serial counter, not a timer.  There is a clock tick
/// per datagram sent out.  This library relies on the client maintaining its
/// own clock, and respects whatever the client provides as far as current and
/// requested clock values.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// Base class from which clients can inherit.  This is how you can store
/// per-request context (state) in the queue, and have it automatically cleaned
/// up.
class Request {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Request(void) throw();

        // netrq::Request class interface methods ------------------------------
        virtual const char * getId(void) const throw() = 0;
        virtual int getMaxBytes(void) const throw() = 0;
        virtual void write(IO xdrbuf::Output * output) = 0;

        /// if non-zero, this request is asking to be resent after the
        ///     specified clock interval
        virtual int getRetryInterval(void) const throw() { return 0; }
};



/// basic network request queue.
///
/// This class is \b threadsafe .  In some situations (single-threaded client)
/// this may be unnecessary overhead, but given the common use case (reacting to
/// or sending UDP diagrams) this isn't expected to be much overhead.
class Queue {
public:
        // public enums --------------------------------------------------------
        enum eInsertResult {
                eQueue_Success                            = 0,
                eQueue_Failed_CurrentEntryHasLaterClock   = 1,
                eQueue_Failed_CurrentEntryHasEarlierClock = 2,

                // keep this last
                eQueue_Failed_Unknown                     = 3
        };

        // virtual destructor --------------------------------------------------
        virtual ~Queue(void) throw();

        // netrq::Queue class interface methods --------------------------------

        /// Returns count of requests in queue.  Approximate only, since other
        /// threads may update the queue by the time the caller gets the count.
        virtual int size(void) = 0;

        /// If the addRequest fails due to a collision, the return value will
        /// tell the client whether the existing request has an earlier or later
        /// clock than what was just requested.
        virtual eInsertResult addRequest(
                                IN dword_t sendClock, ///< send at this clock
                                IN smart_ptr<Request>& request) = 0;

        /// returns the next request that should be sent.  The clock value is
        /// the current packet count, not the time.  So for instance, if you are
        /// using this queue to manage UDP data, increment the clock everytime
        /// you send a UDP packet.
        virtual bool getNextRequest(IN dword_t clock, ///< current clock
                                OUT smart_ptr<Request>& request) = 0;

        /// does the queue already contain a request with this id?
        virtual bool containsRequest(IN const char * id) = 0;

        virtual bool removeRequest(IN const char * id) = 0;

        // static factory methods ----------------------------------------------
        static smart_ptr<Queue> create(void);
};



//
// helper methods
//

/// Given an output buffer, write as many pending requests as possible.  All
/// sent messages are removed from the queue.  Returns the number of messages
/// sent.  See the netrq library comments regarding the clock values.
int sendMessagesFromQueue(IO xdrbuf::Output * output,
                                IN dword_t clock, ///< current clock
                                IO Queue * queue);


};      // netrq namespace

/*@}*/  // end of documentation block

#endif  // WAVEPACKET_NETRQ_H__