Synchronizer.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
///
/// \file
/// \author Gerald Fahrnholz
/// 
/// \defgroup GrpSynchronizer Using Synchronizer
/// @{
/// \ingroup GrpTestUtils 
/// \brief
/// Class Synchronizer allows supports synchronization of parallel
/// activities with linear test sequences
///
/// \sa Synchronizer.h (File documentation)
/// \sa TestToolBox::Synchronizer (class documentation)
/// \sa GrpTestExtensionsForBoostTest (unit test using boost.Test and Synchronizer)
/// 
////////////////////////////////////////////////////////////////////////////////

#pragma once

#include "TestToolBox/CommonSources/ObjectLock.h"
#include "TestToolBox/ISynchronizer.h"

#ifdef USE_TEST_INSTANCE_DLL
#    include "TestToolBox/TestInstanceDll.h"
#endif

namespace TestToolBox
{
struct IEventReceiver;
struct ICallBackFromSynchronizer;

/// Generate a single synchronization event.
/// Typically this method is called when a part of your test environment has received some information
/// from the object under test and has written relevant information to \ref TestToolBox::TestEvents.
/// By rising a sync event it is signalled to the test script that checking of results now is possible.
#define TTB_SYNC()                               TestToolBox::Synchronizer::Get()->Sync     (__FILE__,__LINE__)

/// \brief Waits until the specified number of synchronization events has occured.
#define TTB_WAIT_SYNC()                          TestToolBox::Synchronizer::Get()->WaitSync (__FILE__,__LINE__)

/// Define the maximum time to wait for arriving synchronization events when calling \ref TTB_WAIT_SYNC
#define TTB_SET_SYNC_TIMEOUT(in_timeoutMs)       TestToolBox::Synchronizer::Get()->SetSyncTimeout (in_timeoutMs)

/// Define the number of expected synchronization events for the next call of \ref TTB_WAIT_SYNC
#define TTB_INIT_SYNC(in_numSyncEventsToWaitFor) TestToolBox::Synchronizer::Get()->InitSync       (in_numSyncEventsToWaitFor)


/// \brief This class supports synchronization of parallel activities with a
/// linear test sequence.
///
/// The class counts the number of calls to member function Sync(). When the
/// configured number of calls is reached the blocking call of WaitSync()
/// returns.
///
/// \nosubgrouping 
/// \sa Synchronizer.h (File documentation)
/// \sa GrpTestExtensionsForBoost (unit test using boost.Test and Synchronizer)
/// \sa GrpSynchronizer (Usage documentation)
class Synchronizer :
    public AutoCriticalSection,
    public ISynchronizer
{
private:
///\cond

    /// Constructor
    explicit Synchronizer();
///\endcond

public:
///\cond

    // Destructor
    ~Synchronizer();

    // Get the pointer to the only instance of this class
#ifdef USE_TEST_INSTANCE_DLL
    static Synchronizer* CreateNewInstanceForUsageInDll(void){return new Synchronizer;};
    static Synchronizer* Get (void)
    {return TTB_GetInstance_Synchronizer();}
    static void Cleanup (void)
    {TTB_CleanupInstance_Synchronizer();}
#else
    static Synchronizer* Get (void)
    {if (!s_pSynchronizer) s_pSynchronizer = new Synchronizer;
     return s_pSynchronizer;}
    static Synchronizer* s_pSynchronizer;
    static void Cleanup (void)
    {delete s_pSynchronizer; s_pSynchronizer = 0;}
#endif

///\endcond

    //---------------------------------------------------------------
    /// \name Interface ISynchronizer
    /// \{

    void ConnectWithEventReceiver (IEventReceiver* in_pIEventReceiver);
    void SetSyncTimeout(long in_timeoutMs);
    void InitSync (long in_numSyncEventsToWaitFor);
    void WaitSync(
        const char* in_fileName = 0,
        const long  in_lineNum  = 0);
    void Sync (
        const char* in_fileName = 0,
        const long  in_lineNum  = 0);
    /// \}

private:

    /// Counts calls of Sync()
    long m_curSyncCount;

    /// \brief Counter value at which the wait condition is fulfilled, i.e.
    /// WaitSync() returns
    long m_numSyncEventsToWaitFor;

    /// \brief Maximum timeout to wait if not all sync events occure. If this
    /// timeout elapses WaitSync() returns and an message is written to
    /// test protocol via m_pIEventReceiver.
    long m_syncTimeoutMs;

    /// Handle to the synchronization event
    HANDLE m_hSyncEvent;

    /// Interface for processing all important test situations (e.g. detected error situations)
    IEventReceiver* m_pIEventReceiver;

    /// automatic locking facility
    typedef ObjectLockT<Synchronizer> ObjectLock;

}; // class Synchronizer

///\cond do not document
#ifndef USE_TEST_INSTANCE_DLL
__declspec(selectany) Synchronizer* Synchronizer::s_pSynchronizer = 0;
#endif
///\endcond

}; // namespace TestUtil

/// @} // endGrpSynchronizer

---