1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libovr/Src/OVR_ThreadCommandQueue.h	Sat Sep 14 16:14:59 2013 +0300
     1.3 @@ -0,0 +1,308 @@
     1.4 +/************************************************************************************
     1.5 +
     1.6 +PublicHeader:   None
     1.7 +Filename    :   OVR_ThreadCommandQueue.h
     1.8 +Content     :   Command queue for operations executed on a thread
     1.9 +Created     :   October 29, 2012
    1.10 +Author      :   Michael Antonov
    1.11 +
    1.12 +Copyright   :   Copyright 2012 Oculus VR, Inc. All Rights reserved.
    1.13 +
    1.14 +Use of this software is subject to the terms of the Oculus license
    1.15 +agreement provided at the time of installation or download, or which
    1.16 +otherwise accompanies this software in either electronic or hard copy form.
    1.17 +
    1.18 +************************************************************************************/
    1.19 +
    1.20 +#ifndef OVR_ThreadCommandQueue_h
    1.21 +#define OVR_ThreadCommandQueue_h
    1.22 +
    1.23 +#include "Kernel/OVR_Types.h"
    1.24 +#include "Kernel/OVR_List.h"
    1.25 +#include "Kernel/OVR_Atomic.h"
    1.26 +#include "Kernel/OVR_Threads.h"
    1.27 +
    1.28 +namespace OVR {
    1.29 +
    1.30 +class ThreadCommand;
    1.31 +class ThreadCommandQueue;
    1.32 +
    1.33 +
    1.34 +//-------------------------------------------------------------------------------------
    1.35 +// ***** ThreadCommand
    1.36 +
    1.37 +// ThreadCommand is a base class implementation for commands stored in ThreadCommandQueue.
    1.38 +class ThreadCommand
    1.39 +{
    1.40 +public:    
    1.41 +
    1.42 +    // NotifyEvent is used by ThreadCommandQueue::PushCallAndWait to notify the
    1.43 +    // calling (producer)  thread when command is completed or queue slot is available.
    1.44 +    class NotifyEvent : public ListNode<NotifyEvent>, public NewOverrideBase
    1.45 +    {
    1.46 +        Event E;
    1.47 +    public:   
    1.48 +        NotifyEvent() { }
    1.49 +
    1.50 +        void Wait()        { E.Wait(); }
    1.51 +        void PulseEvent()  { E.PulseEvent(); }
    1.52 +    };
    1.53 +
    1.54 +    // ThreadCommand::PopBuffer is temporary storage for a command popped off
    1.55 +    // by ThreadCommandQueue::PopCommand. 
    1.56 +    class PopBuffer
    1.57 +    {
    1.58 +        enum { MaxSize = 256 };
    1.59 +
    1.60 +        UPInt Size;
    1.61 +        union {            
    1.62 +            UByte Buffer[MaxSize];
    1.63 +            UPInt Align;
    1.64 +        };
    1.65 +
    1.66 +        ThreadCommand* toCommand() const { return (ThreadCommand*)Buffer; }
    1.67 +
    1.68 +    public:
    1.69 +        PopBuffer() : Size(0) { }
    1.70 +        ~PopBuffer();
    1.71 +
    1.72 +        void        InitFromBuffer(void* data);
    1.73 +
    1.74 +        bool        HasCommand() const  { return Size != 0; }
    1.75 +        UPInt       GetSize() const     { return Size; }
    1.76 +        bool        NeedsWait() const   { return toCommand()->NeedsWait(); }
    1.77 +        NotifyEvent* GetEvent() const   { return toCommand()->pEvent; }
    1.78 +
    1.79 +        // Execute the command and also notifies caller to finish waiting,
    1.80 +        // if necessary.
    1.81 +        void        Execute();
    1.82 +    };
    1.83 +    
    1.84 +    UInt16       Size;
    1.85 +    bool         WaitFlag; 
    1.86 +    bool         ExitFlag; // Marks the last exit command. 
    1.87 +    NotifyEvent* pEvent;
    1.88 +
    1.89 +    ThreadCommand(UPInt size, bool waitFlag, bool exitFlag = false)
    1.90 +        : Size((UInt16)size), WaitFlag(waitFlag), ExitFlag(exitFlag), pEvent(0) { }
    1.91 +    virtual ~ThreadCommand() { }
    1.92 +
    1.93 +    bool          NeedsWait() const { return WaitFlag; }
    1.94 +    UPInt         GetSize() const   { return Size; }
    1.95 +
    1.96 +    virtual void            Execute() const = 0;
    1.97 +    // Copy constructor used for serializing this to memory buffer.
    1.98 +    virtual ThreadCommand*  CopyConstruct(void* p) const = 0;
    1.99 +};
   1.100 +
   1.101 +
   1.102 +//-------------------------------------------------------------------------------------
   1.103 +
   1.104 +// CleanType is a template that strips 'const' and '&' modifiers from the argument type;
   1.105 +// for example, typename CleanType<A&>::Type is equivalent to A.
   1.106 +template<class T> struct CleanType           { typedef T Type; };
   1.107 +template<class T> struct CleanType<T&>       { typedef T Type; };
   1.108 +template<class T> struct CleanType<const T>  { typedef T Type; };
   1.109 +template<class T> struct CleanType<const T&> { typedef T Type; };
   1.110 +
   1.111 +// SelfType is a template that yields the argument type. This helps avoid conflicts with
   1.112 +// automatic template argument deduction for function calls when identical argument
   1.113 +// is already defined.
   1.114 +template<class T> struct SelfType { typedef T Type; };
   1.115 +
   1.116 +
   1.117 +
   1.118 +//-------------------------------------------------------------------------------------
   1.119 +// ThreadCommand specializations for member functions with different number of
   1.120 +// arguments and argument types.
   1.121 +
   1.122 +// Used to return nothing from a ThreadCommand, to avoid problems with 'void'.
   1.123 +struct Void
   1.124 +{
   1.125 +    Void() {}
   1.126 +    Void(int) {}
   1.127 +};
   1.128 +
   1.129 +// ThreadCommand for member function with 0 arguments.
   1.130 +template<class C, class R>
   1.131 +class ThreadCommandMF0 : public ThreadCommand
   1.132 +{   
   1.133 +    typedef R (C::*FnPtr)();
   1.134 +    C*      pClass;
   1.135 +    FnPtr   pFn;
   1.136 +    R*      pRet;
   1.137 +
   1.138 +    void executeImpl() const
   1.139 +    {
   1.140 +        pRet ? (void)(*pRet = (pClass->*pFn)()) :
   1.141 +	           (void)(pClass->*pFn)();
   1.142 +    }
   1.143 +
   1.144 +public:    
   1.145 +    ThreadCommandMF0(C* pclass, FnPtr fn, R* ret, bool needsWait)
   1.146 +        : ThreadCommand(sizeof(ThreadCommandMF0), needsWait),
   1.147 +          pClass(pclass), pFn(fn), pRet(ret) { }
   1.148 +
   1.149 +    virtual void           Execute() const { executeImpl(); }
   1.150 +    virtual ThreadCommand* CopyConstruct(void* p) const
   1.151 +    { return Construct<ThreadCommandMF0>(p, *this); }
   1.152 +};
   1.153 +
   1.154 +
   1.155 +// ThreadCommand for member function with 1 argument.
   1.156 +template<class C, class R, class A0>
   1.157 +class ThreadCommandMF1 : public ThreadCommand
   1.158 +{   
   1.159 +    typedef R (C::*FnPtr)(A0);
   1.160 +    C*                           pClass;
   1.161 +    FnPtr                        pFn;
   1.162 +    R*                           pRet;
   1.163 +    typename CleanType<A0>::Type AVal0;
   1.164 +
   1.165 +    void executeImpl() const
   1.166 +    {
   1.167 +      pRet ? (void)(*pRet = (pClass->*pFn)(AVal0)) :
   1.168 +	         (void)(pClass->*pFn)(AVal0);
   1.169 +    }
   1.170 +
   1.171 +public:    
   1.172 +    ThreadCommandMF1(C* pclass, FnPtr fn, R* ret, A0 a0, bool needsWait)
   1.173 +        : ThreadCommand(sizeof(ThreadCommandMF1), needsWait),
   1.174 +          pClass(pclass), pFn(fn), pRet(ret), AVal0(a0) { }
   1.175 +
   1.176 +    virtual void           Execute() const { executeImpl(); }
   1.177 +    virtual ThreadCommand* CopyConstruct(void* p) const
   1.178 +    { return Construct<ThreadCommandMF1>(p, *this); }
   1.179 +};
   1.180 +
   1.181 +// ThreadCommand for member function with 2 arguments.
   1.182 +template<class C, class R, class A0, class A1>
   1.183 +class ThreadCommandMF2 : public ThreadCommand
   1.184 +{   
   1.185 +    typedef R (C::*FnPtr)(A0, A1);
   1.186 +    C*                            pClass;
   1.187 +    FnPtr                         pFn;
   1.188 +    R*                            pRet;
   1.189 +    typename CleanType<A0>::Type  AVal0;
   1.190 +    typename CleanType<A1>::Type  AVal1;
   1.191 +
   1.192 +    void executeImpl() const
   1.193 +    {
   1.194 +        pRet ? (void)(*pRet = (pClass->*pFn)(AVal0, AVal1)) :
   1.195 +	           (void)(pClass->*pFn)(AVal0, AVal1);
   1.196 +    }
   1.197 +
   1.198 +public:    
   1.199 +    ThreadCommandMF2(C* pclass, FnPtr fn, R* ret, A0 a0, A1 a1, bool needsWait)
   1.200 +        : ThreadCommand(sizeof(ThreadCommandMF2), needsWait),
   1.201 +          pClass(pclass), pFn(fn), pRet(ret), AVal0(a0), AVal1(a1) { }
   1.202 +    
   1.203 +    virtual void           Execute() const { executeImpl(); }
   1.204 +    virtual ThreadCommand* CopyConstruct(void* p) const 
   1.205 +    { return Construct<ThreadCommandMF2>(p, *this); }
   1.206 +};
   1.207 +
   1.208 +
   1.209 +//-------------------------------------------------------------------------------------
   1.210 +// ***** ThreadCommandQueue
   1.211 +
   1.212 +// ThreadCommandQueue is a queue of executable function-call commands intended to be
   1.213 +// serviced by a single consumer thread. Commands are added to the queue with PushCall
   1.214 +// and removed with PopCall; they are processed in FIFO order. Multiple producer threads
   1.215 +// are supported and will be blocked if internal data buffer is full.
   1.216 +
   1.217 +class ThreadCommandQueue
   1.218 +{
   1.219 +public:
   1.220 +
   1.221 +    ThreadCommandQueue();
   1.222 +    virtual ~ThreadCommandQueue();
   1.223 +
   1.224 +
   1.225 +    // Pops the next command from the thread queue, if any is available.
   1.226 +    // The command should be executed by calling popBuffer->Execute().
   1.227 +    // Returns 'false' if no command is available at the time of the call.
   1.228 +    bool PopCommand(ThreadCommand::PopBuffer* popBuffer);
   1.229 +
   1.230 +    // Generic implementaion of PushCommand; enqueues a command for execution.
   1.231 +    // Returns 'false' if push failed, usually indicating thread shutdown.
   1.232 +    bool PushCommand(const ThreadCommand& command);
   1.233 +
   1.234 +    // 
   1.235 +    void PushExitCommand(bool wait);
   1.236 +
   1.237 +    // Returns 'true' once ExitCommand has been processed, so the thread can shut down.
   1.238 +    bool IsExiting() const;
   1.239 +
   1.240 +
   1.241 +    // These two virtual functions serve as notifications for derived
   1.242 +    // thread waiting.    
   1.243 +    virtual void OnPushNonEmpty_Locked() { }
   1.244 +    virtual void OnPopEmpty_Locked()     { }
   1.245 +
   1.246 +
   1.247 +    // *** PushCall with no result
   1.248 +    
   1.249 +    // Enqueue a member function of 'this' class to be called on consumer thread.
   1.250 +    // By default the function returns immediately; set 'wait' argument to 'true' to
   1.251 +    // wait for completion.
   1.252 +    template<class C, class R>
   1.253 +    bool PushCall(R (C::*fn)(), bool wait = false)
   1.254 +    { return PushCommand(ThreadCommandMF0<C,R>(static_cast<C*>(this), fn, 0, wait)); }       
   1.255 +    template<class C, class R, class A0>
   1.256 +    bool PushCall(R (C::*fn)(A0), typename SelfType<A0>::Type a0, bool wait = false)
   1.257 +    { return PushCommand(ThreadCommandMF1<C,R,A0>(static_cast<C*>(this), fn, 0, a0, wait)); }
   1.258 +    template<class C, class R, class A0, class A1>
   1.259 +    bool PushCall(R (C::*fn)(A0, A1),
   1.260 +                  typename SelfType<A0>::Type a0, typename SelfType<A1>::Type a1, bool wait = false)
   1.261 +    { return PushCommand(ThreadCommandMF2<C,R,A0,A1>(static_cast<C*>(this), fn, 0, a0, a1, wait)); }
   1.262 +    // Enqueue a specified member function call of class C.
   1.263 +    // By default the function returns immediately; set 'wait' argument to 'true' to
   1.264 +    // wait for completion.
   1.265 +    template<class C, class R>
   1.266 +    bool PushCall(C* p, R (C::*fn)(), bool wait = false)
   1.267 +    { return PushCommand(ThreadCommandMF0<C,R>(p, fn, 0, wait)); }
   1.268 +    template<class C, class R, class A0>
   1.269 +    bool PushCall(C* p, R (C::*fn)(A0), typename SelfType<A0>::Type a0, bool wait = false)
   1.270 +    { return PushCommand(ThreadCommandMF1<C,R,A0>(p, fn, 0, a0, wait)); }
   1.271 +    template<class C, class R, class A0, class A1>
   1.272 +    bool PushCall(C* p, R (C::*fn)(A0, A1),
   1.273 +                  typename SelfType<A0>::Type a0, typename SelfType<A1>::Type a1, bool wait = false)
   1.274 +    { return PushCommand(ThreadCommandMF2<C,R,A0,A1>(p, fn, 0, a0, a1, wait)); }
   1.275 +    
   1.276 +    
   1.277 +    // *** PushCall with Result
   1.278 +
   1.279 +    // Enqueue a member function of 'this' class call and wait for call to complete
   1.280 +    // on consumer thread before returning.
   1.281 +    template<class C, class R>
   1.282 +    bool PushCallAndWaitResult(R (C::*fn)(), R* ret)
   1.283 +    { return PushCommand(ThreadCommandMF0<C,R>(static_cast<C*>(this), fn, ret, true)); }       
   1.284 +    template<class C, class R, class A0>
   1.285 +    bool PushCallAndWaitResult(R (C::*fn)(A0), R* ret, typename SelfType<A0>::Type a0)
   1.286 +    { return PushCommand(ThreadCommandMF1<C,R,A0>(static_cast<C*>(this), fn, ret, a0, true)); }
   1.287 +    template<class C, class R, class A0, class A1>
   1.288 +    bool PushCallAndWaitResult(R (C::*fn)(A0, A1), R* ret,
   1.289 +                               typename SelfType<A0>::Type a0, typename SelfType<A1>::Type a1)
   1.290 +    { return PushCommand(ThreadCommandMF2<C,R,A0,A1>(static_cast<C*>(this), fn, ret, a0, a1, true)); }
   1.291 +    // Enqueue a member function call for class C and wait for the call to complete
   1.292 +    // on consumer thread before returning.
   1.293 +    template<class C, class R>
   1.294 +    bool PushCallAndWaitResult(C* p, R (C::*fn)(), R* ret)
   1.295 +    { return PushCommand(ThreadCommandMF0<C,R>(p, fn, ret, true)); }
   1.296 +    template<class C, class R, class A0>
   1.297 +    bool PushCallAndWaitResult(C* p, R (C::*fn)(A0), R* ret, typename SelfType<A0>::Type a0)
   1.298 +    { return PushCommand(ThreadCommandMF1<C,R,A0>(p, fn, ret, a0, true)); }
   1.299 +    template<class C, class R, class A0, class A1>
   1.300 +    bool PushCallAndWaitResult(C* p, R (C::*fn)(A0, A1), R* ret,
   1.301 +                               typename SelfType<A0>::Type a0, typename SelfType<A1>::Type a1)
   1.302 +    { return PushCommand(ThreadCommandMF2<C,R,A0,A1>(p, fn, ret, a0, a1, true)); }
   1.303 +
   1.304 +private:
   1.305 +    class ThreadCommandQueueImpl* pImpl;
   1.306 +};
   1.307 +
   1.308 +
   1.309 +}
   1.310 +
   1.311 +#endif // OVR_ThreadCommandQueue_h