"Fossies" - the Fresh Open Source Software Archive

Member "muscle/reflector/AbstractSessionIOPolicy.h" (8 Jun 2019, 7717 Bytes) of package /linux/privat/muscle7.30.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "AbstractSessionIOPolicy.h" see the Fossies "Dox" file reference documentation.

    1 /* This file is Copyright 2000-2013 Meyer Sound Laboratories Inc.  See the included LICENSE.txt file for details. */
    2 
    3 #ifndef AbstractSessionIOPolicy_h
    4 #define AbstractSessionIOPolicy_h
    5 
    6 #include "util/RefCount.h"
    7 #include "util/PulseNode.h"
    8 
    9 namespace muscle {
   10 
   11 class AbstractReflectSession;
   12 class ReflectServer;
   13 
   14 /** A simple data-holding class; holds an AbstractSessionIOPolicy and a boolean to
   15   * indicate whether it is using us as an input or not.  Keeping the two
   16   * values together here lets us use them as a "key".
   17   */
   18 class PolicyHolder
   19 {
   20 public:
   21    /** Default Constructor.  Sets session to NULL and asInput to false */
   22    PolicyHolder() : _session(NULL), _asInput(false) {/* empty */}
   23 
   24    /** Constructor.  Sets our held values as specified by the arguments. 
   25      * @param session the AbstractReflectSession object that we will be in use by
   26      * @param asInput true iff we're being used to regulate input data, false if we're being used to regulate output data
   27      */
   28    PolicyHolder(AbstractReflectSession * session, bool asInput) : _session(session), _asInput(asInput) {/* empty */}
   29 
   30    /** Returns the session object this PolicyHolder is being used by (as passed in to the constructor) */
   31    AbstractReflectSession * GetSession() const {return _session;}
   32 
   33    /** Returns true iff this PolicyHolder is being used to regulate input data (as passed in to the constructor) */
   34    bool IsAsInput() const {return _asInput;}
   35 
   36    /** @copydoc DoxyTemplate::HashCode() const */
   37    uint32 HashCode() const {return ((uint32)((uintptr)_session))+(_asInput?1:0);}  // double-cast for AMD64
   38 
   39    /** @copydoc DoxyTemplate::operator==(const DoxyTemplate &) const */
   40    bool operator == (const PolicyHolder & rhs) {return ((rhs._session == _session)&&(rhs._asInput == _asInput));}
   41 
   42 private:
   43    AbstractReflectSession * _session;
   44    bool _asInput;
   45 };
   46 
   47 /**
   48  * This class is an interface for objects that can be used by a ReflectServer
   49  * to control how and when I/O in a particular direction is performed for a
   50  * session or group of sessions.  Its primary use is to implement aggregate
   51  * bandwidth limits for certain sessions or groups of sessions.  Each
   52  * AbstractReflectSession can associate itself an IO policy for reading,
   53  * and an IO policy for writing, if it likes.
   54  * <p>
   55  * ReflectServer calls the methods in this API in the following sequence:
   56  * <ol>
   57  *  <li>BeginIO() called</li>
   58  *  <li>OkayToTransfer() (called once for each session that wants to transfer data)</li>
   59  *  <li>GetMaxTransferChunkSize() (called once for each session that was given the okay in the previous step())</li>
   60  *  <li>server blocks until an event is ready, and then calls DoInput() and/or DoOutput() on sessions that need it()</li>
   61  *  <li>EndIO() called()</li>
   62  *  <li>Lather, rinse, repeat</li>
   63  * </ol>
   64  */
   65 class AbstractSessionIOPolicy : public PulseNode, public RefCountable
   66 {
   67 public:
   68    /** Default constructor. */
   69    AbstractSessionIOPolicy() : _hasBegun(false) {/* empty */}
   70 
   71    /** Destructor. */
   72    virtual ~AbstractSessionIOPolicy() {/* empty */}
   73 
   74    /** Called whenever an AbstractReflectSession chooses us as one of his policies of choice.
   75      * Guaranteed not be called between calls to BeginIO() and EndIO().
   76      * @param holder An object containing info on the AbstractReflectSession that
   77      *               is now using this policy.
   78      */
   79    virtual void PolicyHolderAdded(const PolicyHolder & holder) = 0;
   80 
   81    /** Called whenever an AbstractReflectSession cancels one of his policies with us.
   82      * Guaranteed not be called between calls to BeginIO() and EndIO().
   83      * @param holder An object containing info on the AbstractReflectSession that
   84      *               is nolonger using this policy.  Note that the contained
   85      *               session may be in the process of being destroyed, so while
   86      *               it is still a valid AbstractReflectSession, it may no longer
   87      *               be a valid object of its original subclass.
   88      */
   89    virtual void PolicyHolderRemoved(const PolicyHolder & holder) = 0;
   90 
   91    /** Called once at the beginning of each pass through our I/O event loop.
   92      * @param now The time at which the loop is beginning, for convenience.
   93      */
   94    virtual void BeginIO(uint64 now) = 0;
   95 
   96    /** Should return true iff we want to allow the given session to be able to transfer
   97      * bytes to/from its DataIO object.
   98      * Called after BeginIO() for each iteration. Only called for the sessions
   99      * that want to transfer data (i.e. whose gateway objects returned true from their
  100      * IsReadyForInput() or HasBytesToOutput() methods), so you can determine the set
  101      * of 'active' sessions based on what gets called here.
  102      * @param holder a session who wishes to transfer data.  Guaranteed to be one of
  103      *               our current PolicyHolders, and attached to the server.
  104      * @returns true iff we want to let the session transfer, false if not.
  105      *               (Returning false keeps the session's socket from being included
  106      *                in the select() call, so the server won't be awoken even if the
  107      *                session's socket becomes ready)
  108      */
  109    virtual bool OkayToTransfer(const PolicyHolder & holder) = 0;
  110 
  111    /** Should return the maximum number of bytes that the given session is allowed to
  112      * transfer to/from its IOGateway's DataIO during the next I/O stage of our event loop.
  113      * Called after all the calls to OkayToTransfer() have been done.
  114      * Called once for each session that we previously returned true for from our
  115      * OkayToTransfer() method.
  116      * You may return MUSCLE_NO_LIMIT if you want the session to be able to transfer as
  117      * much as it likes, or 0 if we want the session to not transfer anything at all (or
  118      * any number in between, of course).
  119      * (If you are returning 0 here, it's usually better to just have
  120      *  OkayToTransfer() return false for this PolicyHolder instead...
  121      *  that way the server won't keep waking up to service a session that won't allowed
  122      *  to transfer anything anyway)
  123      * @param holder A session to get a limit for.  Guaranteed to be one of our current
  124      *               PolicyHolders, and attached to the server.
  125      * @returns The max number of bytes the session is allowed to transfer, for now.
  126      *          This value will be passed in to the session's gateway's DoInput()
  127      *          or DoOutput() method, as appropriate.
  128      */
  129    virtual uint32 GetMaxTransferChunkSize(const PolicyHolder & holder) = 0;
  130 
  131    /** Called to notify you that the given session transferred the given
  132      * number of bytes to/from its DataIO object.
  133      * @param holder A session which transferred some bytes.  Guaranteed to be one of our
  134      *               PolicyHolders, and attached to the server.
  135      * @param numBytes How many bytes it transferred.  This value will be less than or equal
  136      *                 to the max value you return previously for this session from
  137      *                 GetMaxReadChunkSize().
  138      */
  139    virtual void BytesTransferred(const PolicyHolder & holder, uint32 numBytes) = 0;
  140 
  141    /** Called once at the end of each pass through our I/O event loop.
  142      * @param now The time at which the loop is ending, for convenience.
  143      */
  144    virtual void EndIO(uint64 now) = 0;
  145 
  146 private:
  147    friend class ReflectServer;
  148    bool _hasBegun;  // used by the ReflectServer
  149 
  150    DECLARE_COUNTED_OBJECT(AbstractSessionIOPolicy);
  151 };
  152 DECLARE_REFTYPES(AbstractSessionIOPolicy);
  153 
  154 } // end namespace muscle
  155 
  156 // At the bottom to avoid circular-forward-reference problems, while
  157 // still allowing subclasses to automatically get this header
  158 #include "reflector/AbstractReflectSession.h"
  159 
  160 #endif