Thread.cpp

Go to the documentation of this file.

//==---------------------------------------------------------------------------
// Project: uLib utility library.
// Module: Threads that can be safely killed (unlike TerminateThread).
// License: Released under the NNOSL (See NNOSL.txt in the base directory).
//
// Author: Love Nystrom 2017 <neo.love@hotmail.com>
// Author: Based on code by Jeff Richter 1995, published in MSJ March 1996.
//
// Jeff's article contains the following disclaimer:
//
//   The information contained herein is not endorsed by Microsoft.
//   Microsoft makes no warranty as to the accuracy or the completeness of the
//   information. Users are advised that they use this at their own risk.
//
//==---------------------------------------------------------------------------
// NOTE: Requires /EHa compiler switch to perform stack unwinding correctly.
//==---------------------------------------------------------------------------

#include <uLib/Common.h>
#ifdef HAVE_STRUCTURED_EH
#include <uLib/Thread.h>
#include <uLib/Debug.h>
#include <uLib/UtilFunc.h>

BEGIN_NAMESPACE( uLib ) // The following two species are wrapped in our namespace.

//==---------------------------------------------------------------------------
//  SimpleThread (Note: this is not the killsafe species)
//==---------------------------------------------------------------------------

SimpleThread::SimpleThread()
: hThread( NULL ), Id( 0 ), UserData( NULL )
{}

SimpleThread::~SimpleThread()
{
    Stop();
}

bool SimpleThread::Start( PTHREAD_START_ROUTINE ThreadFunc, DWORD msYield )
{
    bool ok = (hThread == NULL);
    if ( !ok ) SetLastError( ERROR_ALREADY_INITIALIZED );
    else
    {
        hThread = CreateThread( NULL,0, ThreadFunc, this, 0, (PDWORD)&Id );
        // Letting the calling thread sleep a bit should schedule the new thread promptly.
        if (hThread && msYield) SleepEx( msYield, true );
        ok = (hThread != NULL);
    }
    return ok;
}

bool SimpleThread::Stop( DWORD msWait )
{
    bool ok = (hThread == NULL);
    if ( !ok )
    {
        Id = 0; // Set the stop signal.
        DWORD error = 0;
        ok = WaitFor( hThread, msWait );
        if ( !ok )
        {
            TRACE( DP_ERROR, 
                _F("Terminating unresponsive thread 0x%04x. Debug your code!\n"), 
                GetCurrentThreadId()
                );
            error = WAIT_TIMEOUT;
            TerminateThread( hThread, error );
        }
        Close();
        if (error) SetLastError( error );
    }
    return ok;
}

void SimpleThread::Close()
{
    hThread = CloseHandleEx( hThread );
    Id = 0;
}

//==---------------------------------------------------------------------------
//  Thread. Based on Jeff Richter's code from 1995. Big thanks :)
//==---------------------------------------------------------------------------

// Our very own software exception.
// This exception is raised when a thread is being killed.
// MAKE_SOFTWARE_EXCEPTION --> Common.h

#define SE_KILLTHREAD \
    MAKE_SOFTEXCEPTION( ERROR_SEVERITY_ERROR, FACILITY_ULIB, 1 )

// Macros used to abstract the instruction pointer register
// for the various CPU platforms.

#if defined(_X86_)
#define PROGCTR(Context)  (Context.Eip)
#endif

#if defined(_M_AMD64) // x64
#define PROGCTR(Context)  (Context.Rip)
#endif

#if defined(_MIPS_)
#define PROGCTR(Context)  (Context.Fir)
#endif

#if defined(_ALPHA_)
#define PROGCTR(Context)  (Context.Fir)
#endif

#if defined(_PPC_)
#define PROGCTR(Context)  (Context.Iar)
#endif

#if !defined(PROGCTR)
#error Module contains CPU-specific code; modify and recompile.
#endif

#ifdef INCL_THREAD_W95_SUPPORT
static PVOID CreateExceptionHandlerThunks( PHANDLE phFileMap );
static void DeleteExceptionHandlerThunks( PVOID pvThunk, HANDLE hFileMap );
#endif

//==---------------------------------------------------------------------------

static THREADPROC __dummyThr( PVOID arg ) {
    Thread* _this = (Thread*) arg;
    while( _this->idThread ) SleepEx( 1000, true );
    return 0;
    }

//==---------------------------------------------------------------------------

Thread::Thread(
    PTHREAD_START_ROUTINE pFunc,
    SIZE_T StackSize, DWORD Flags, PSECURITY_ATTRIBUTES pSec
    )
{
    UserData = NULL;
    hThread = NULL;
    idThread = 0;

    // Kludge for the descendant Execute dilemma: __dummyThr. See Start().
    _ThreadFunc = pFunc ? pFunc : __dummyThr;

    _SecAttr = pSec;
    _StkSize = StackSize;
    _Flags = Flags;

    _hmControl = _hmDelay = _heEnd = NULL;
    _DelayCount = 0;

    #ifdef INCL_THREAD_W95_SUPPORT
    _pThunk = NULL;
    _hFileMap = NULL;
    #endif
}

Thread::~Thread()
{
    Stop( 3000 );
}

bool Thread::SetThreadProc( PTHREAD_START_ROUTINE pFunc )
{
    bool ok = (pFunc != NULL);
    if (!ok) SetLastError( ERROR_INVALID_PARAMETER );
    else
    {
        if (hThread) // Running, so fail
        {
            SetLastError( ERROR_ALREADY_ASSIGNED );
            ok = false;
        }
        else // Not running, so set the function pointer
        {
            _ThreadFunc = pFunc;
        }
    }
    return ok;
}

// Start the thread if it's not running already.


bool Thread::Start()
{
    typedef unsigned (__stdcall *PCRT_THREADFUNC)( void* arg );

    if (!hThread)
    {
        // The descendant Execute dilemma: They don't need/use _ThreadFunc,
        // but I won't sacrifice the pointer check. See __dummyThr in the ctor.

        if (!_ThreadFunc) SetLastError( ERROR_INVALID_FUNCTION );
        else
        {
            _DelayCount = 0; // Reset counter
            _hmControl = CreateMutex( NULL, FALSE, NULL );
            _hmDelay = CreateMutex( NULL, FALSE, NULL );
            _heEnd = CreateEvent( NULL, TRUE, FALSE, NULL );

            #ifdef INCL_THREAD_W95_SUPPORT
            if (_TLSIndex == TLS_OUT_OF_INDEXES) _TLSIndex = TlsAlloc();
            #endif

            // Start the thread at our wrapper function _TProc,
            // which then calls Execute, which by default calls _ThreadFunc.

            hThread = (HANDLE)_beginthreadex(
                _SecAttr, (UINT)_StkSize, (PCRT_THREADFUNC)_TProc, this,
                _Flags, (PUINT)&idThread
                );
            Sleep( 10 ); // Yield a little CPU time so thread can be scheduled.
        }
    }
    return (hThread != NULL);
}

// Stop the thread. Kill it if it's not responding.

bool Thread::Stop( DWORD msWait, bool Nuke )
{
    if (hThread)
    {
        idThread = 0; // Signal the thread to break it's loop.
        if (!WaitFor( hThread, msWait ))
        {
            DPrint( DP_WARNING,_F("Killing unresponsive thread.\n") );
            // Raise an exception in the thread to terminate it.
            if ( !Kill() )
            {
                // Kill is pending due to DelayDeath. Wait another msWait.
                if (Nuke && !WaitFor( hThread, msWait ))
                {
                    // Nuke is allowed and e.g. pending I/O can't be aborted...
                    // ... Last resort: Call TerminateThread.
                    // This may cause internal leaks, undefined run-state, and various havoc.
                    DPrint( DP_ERROR,_F("ALERT: Forced to use TerminateThread !!\n") );
                    #ifndef __GNUC__
                      BREAK(); // GCC flips the lid... again :/
                    #endif
                    TerminateThread( hThread, ERROR_TIMEOUT );
                }
            }
        }
        _Cleanup( true );
    }
    return (hThread == NULL);
}

bool Thread::Pause( bool pause ) // Pause/resume the thread.
{
    if (pause) SuspendThread( hThread );
    else ResumeThread( hThread );
    return pause;
}

bool Thread::Kill() // For controller. Force thread to terminate.
{
    // The control thread calls this function to kill a worker thread.
    // If the worker thread is not currently protected by DelayDeath, we attempt
    // to kill the thread now by suspending it, changing it's instruction pointer
    // to ForceDeath, and resuming the thread.  Effectively we are raising
    // an exception in the worker thread.  If the worker thread is protected by
    // DelayDeath, we simply set an event and let the thread kill itself
    // when it calls DelayDeath( false ) to ends its protection.

    bool rip = false; // Rest in peace
    WaitForSingleObject( _hmControl, INFINITE ); // PONDER: Ought to *not* be INFINITE...

    if (WaitForSingleObject( _hmDelay, 0 ) == WAIT_TIMEOUT)
    {
        // The thread is delaying its death,
        // Set a flag that the thread will check later.

        SetEvent( _heEnd );
    }
    else // The thread can be terminated now!
    {
        if (WaitForSingleObject( hThread, 0 ) == WAIT_TIMEOUT)
        {
            // The worker has not yet terminated.
            
            SuspendThread( hThread ); // Stop the thread

            // Get the worker thread's current CPU registers.

            CONTEXT ctx = {0};
            ctx.ContextFlags = CONTEXT_CONTROL;
            GetThreadContext( hThread, &ctx );

            // Change the instruction pointer to our death function.

            PROGCTR(ctx) = (DWORD_PTR)_ForceDeath;
            SetThreadContext( hThread, &ctx );

            // Resuming the thread forces our function to be called which
            // raises an SE_KILLTHREAD exception in the worker thread.

            ResumeThread( hThread );
            rip = true;
        }
        ReleaseMutex( _hmDelay );
    }
    ReleaseMutex( _hmControl );
    return rip;
}

void Thread::DelayDeath( bool enable )
{
    // This function is used to allow the thread to protect sections of code
    // from termination by the control thread. Call DelayDeath( true ) to
    // start protection from Kill() and DelayDeath( false ) to end protection.
    // Multiple DelayDeath( true ) calls are allowed. A delay count is
    // maintained and the thread remains protected until the count is 0.

    WaitForSingleObject( _hmControl, INFINITE ); // PONDER: Ought to *not* be INFINITE.

    if (enable)
    {
        // The thread wants to delay its death. We get and keep
        // the _hmDelay mutex while protected from termination by Kill.

        WaitForSingleObject( _hmDelay, INFINITE );
        _DelayCount++;
    }
    else // The thread wants to allow its death.
    {
        _DelayCount--;
        ReleaseMutex( _hmDelay );

        // If the delay death count is zero and Kill has been called
        // then force the thread to terminate now.

        if ((_DelayCount == 0)
        && (WaitForSingleObject( _heEnd, 0 ) == WAIT_OBJECT_0))
        {
            _ForceDeath();
        }
    }
    ReleaseMutex( _hmControl );
}

//==---------------------------------------------------------------------------

void Thread::_Cleanup( bool closeThr )
{
    if (closeThr)
    {
        hThread = CloseHandleEx( hThread );
        idThread = 0;
    }
    _hmControl = CloseHandleEx( _hmControl );
    _hmDelay = CloseHandleEx( _hmDelay );
    _heEnd = CloseHandleEx( _heEnd );
}

#pragma message("MEMO: [Thread] _TProc requires /EHa compiler switch > " __FILE__ ":" PP_NSTR(__LINE__))
// ... in order to peform stack unwind properly and call local destructors.

static UINT __tpExFilter( UINT xcodeAct, PEXCEPTION_POINTERS pxp )
{
    return (xcodeAct == pxp->ExceptionRecord->ExceptionCode)
        ? EXCEPTION_EXECUTE_HANDLER : EXCEPTION_CONTINUE_SEARCH;
}

THREADPROC Thread::_TProc( PVOID Arg ) // static
{
    // The user's thread function is called from this "real" thread function.
    // The new thread starts here because we need to wrap the call to the actual
    // thread function in an SEH __try block and to perform cleanup just before
    // the thread dies.

    PThread _this = (PThread) Arg;
    DWORD ExitCode = 0;

    __try
    {
        __try
        {
            #ifdef INCL_THREAD_W95_SUPPORT // The index is pre-allocated
            TlsSetValue( Thread::_TLSIndex, _this );
            #endif

            ExitCode = _this->Execute();
        }

        // If the exception occurs because our thread is forcibly being killed,
        // execute our handler (the system does a global unwind first).

        __except( __tpExFilter( SE_KILLTHREAD, GetExceptionInformation() ))
        {
            ExitCode = ERROR_DBG_RIPEXCEPTION; // Not really, but RIP seems appropriate.
            #ifdef INCL_THREAD_W95_SUPPORT
            DeleteExceptionHandlerThunks( _this->_pThunk, _this->_hFileMap );
            #endif
        }
        __end_except // GCC kludge
    }
    __finally // This executes even if the thread is dying.
    {
        _this->_Cleanup( true );

        #ifdef INCL_THREAD_W95_SUPPORT
        TlsSetValue( Thread::_TLSIndex, NULL );
        #endif
    }
    __end_finally // GCC kludge

    return ExitCode;
}

// Terminate the worker thread by getting it to execute this function

void Thread::_ForceDeath( void ) // static
{
    #ifdef INCL_THREAD_W95_SUPPORT // Work around Windows 95 execption problem.
    PThread _this = (PThread) TlsGetValue( Thread::_TLSIndex );
    _this->_pThunk = CreateExceptionHandlerThunks( &_this->_hFileMap );
    #endif

    RaiseException( SE_KILLTHREAD, EXCEPTION_NONCONTINUABLE, 0, NULL );
    // RaiseException is dispatched and never returns
}

//==---------------------------------------------------------------------------
#ifdef INCL_THREAD_W95_SUPPORT // Work around Windows 95 execption problem
//==---------------------------------------------------------------------------

DWORD Thread::_TLSIndex = TLS_OUT_OF_INDEXES; // Gives static access to this.

// Internal structure of the exception handler chain.
// This structure is documented, compiler writers need
// this information, but it's missing from the header files.

typedef struct _EXCEPTIONREGISTRATIONRECORD {
    _EXCEPTIONREGISTRATIONRECORD *pexrr;
    PVOID pvHandler; // pointer to the exception handler function
} EXCEPTIONREGISTRATIONRECORD, *PEXCEPTIONREGISTRATIONRECORD;

// This marks the end of the chain

const PEXCEPTIONREGISTRATIONRECORD pexrrEndMark =
    (PEXCEPTIONREGISTRATIONRECORD) 0xFFFFFFFF;

// This is the lowest shared address

const PVOID pvSharedMin = (PVOID) 0x80000000;

// Code for thunks

static const BYTE _MovAxImm[] = { (BYTE)'\xB8' };            // MOV EAX, imm
static const BYTE _JmpAx[] = { (BYTE)'\xFF', (BYTE)'\xE0' }; // JMP EAX

// Structure of thunk. We use byte arrays to avoid any possibility
// of alignment problems (we do NOT want alignment).

typedef struct {
    BYTE abMovAxImm[ sizeof(_MovAxImm) ];
    BYTE abJmpAddr[ sizeof(PROC) ];  // Size of a function pointer
    BYTE abJmpAx[ sizeof(_JmpAx) ];
} EXCEPTTHUNK, *PEXCEPTTHUNK;

static PVOID CreateExceptionHandlerThunks( PHANDLE phFileMap )
{
    // This functions works around a problem that only exists on Windows 95
    // when KillThrd_Kill interrupts the worker thread while in a system
    // call. When an exception is raised from within a system call on
    // Windows 95, only system exception handlers are called, user exception
    // handlers are not.  This can prevent KillThrd_ThreadFunc from handling
    // the SE_KILLLTHREAD exception. We are able to trick the system into
    // behaving as if all the handlers are system handlers by creating
    // thunks in shared memory to call the actual exception handlers.

    // WARNING: Windows 95 was trying to protect us but we are defeating it.
    // The system may be in an unusual state when the exception filters and
    // handlers are processed. You should be sure they do not delay the
    // termination of the thread.

    PVOID pvRet = NULL;
    PEXCEPTIONREGISTRATIONRECORD pexrrHead;
    PEXCEPTIONREGISTRATIONRECORD pexrrCur;
    PEXCEPTTHUNK pThunk;
    OSVERSIONINFO osvi;

    osvi.dwOSVersionInfoSize = sizeof(osvi);
    GetVersionEx( &osvi );
    BOOL fIsWin95 = (osvi.dwPlatformId == VER_PLATFORM_WIN32_WINDOWS);
    int nThunkCnt;

    if (fIsWin95)
    {
        // Get the head of the SEH handler chain
        __asm mov eax, fs:[0]
        __asm mov pexrrHead, eax

        // First calculate the number of thunks we need to create
        pexrrCur = pexrrHead;
        nThunkCnt = 0;
        while (pexrrEndMark != pexrrCur)
        {
            // Don't thunk system handlers,
            if (pexrrCur->pvHandler < pvSharedMin)
            {
                nThunkCnt++;
            }
            pexrrCur = pexrrCur->pexrr;
        }

        // Allocate shared storage for the thunks (+1 for sentinel value)

        *phFileMap = CreateFileMapping(
            INVALID_HANDLE_VALUE, NULL, PAGE_READWRITE,
            0, (nThunkCnt+1) * sizeof(EXCEPTTHUNK), NULL
            );
        if (NULL != *phFileMap)
        {
            pvRet = MapViewOfFile( *phFileMap, FILE_MAP_WRITE, 0,0,0 );
            if (NULL == pvRet)
            {
                CloseHandle( *phFileMap );
                *phFileMap = NULL;
            }
            else
            {
                pThunk = (PEXCEPTTHUNK) pvRet;
                pexrrCur = pexrrHead;

                while( 0 < nThunkCnt )
                {
                    // Only thunk user handlers
                    if (pexrrCur->pvHandler < pvSharedMin)
                    {
                        // Build the thunk in shared memory

                        CopyMemory( pThunk->abMovAxImm, _MovAxImm, sizeof(pThunk->abMovAxImm) );
                        CopyMemory( pThunk->abJmpAddr, &pexrrCur->pvHandler, sizeof(pThunk->abJmpAddr) );
                        CopyMemory( pThunk->abJmpAx, _JmpAx, sizeof(pThunk->abJmpAx) );

                        // Make the execption record point to thunk

                        pexrrCur->pvHandler = (PVOID) pThunk;
                        pThunk++;
                        nThunkCnt--;
                    }
                    pexrrCur = pexrrCur->pexrr;
                }
                // Null terminate list
                FillMemory( pThunk, sizeof(pThunk), 0 );
            }
        }
    }
    return pvRet;
}

static void DeleteExceptionHandlerThunks( PVOID pvThunk, HANDLE hFileMap )
{
    PEXCEPTIONREGISTRATIONRECORD pexrrCur;
    PEXCEPTTHUNK pThunk;
    PEXCEPTTHUNK pThunkCur;
    int nThunkCnt = 0;

    if (NULL != pvThunk)
    {
        // Get the head of the SEH handler chain
        __asm mov eax, fs:[0]
        __asm mov pexrrCur, eax

        pThunk = (PEXCEPTTHUNK) pvThunk;

        // Count he number of entries in the null terminated thunk list

        while( '\0' != pThunk[nThunkCnt].abMovAxImm[0] )
        {
            nThunkCnt++;
        }

        // Loop through the exception handler list

        while (pexrrEndMark != pexrrCur)
        {
            if ( (PVOID) pThunk <= pexrrCur->pvHandler
            && pexrrCur->pvHandler < (PVOID) &pThunk[nThunkCnt] )
            {
                // This exception handler is pointing into our thunk table
                // unthunk the entry

                pThunkCur = (PEXCEPTTHUNK) pexrrCur->pvHandler;
                CopyMemory( &pexrrCur->pvHandler, pThunkCur->abJmpAddr, sizeof(pexrrCur->pvHandler) );
            }
            pexrrCur = pexrrCur->pexrr;
        }
        UnmapViewOfFile( pvThunk );
    }

    if (NULL != hFileMap) CloseHandle( hFileMap );
}

#endif//def INCL_THREAD_W95_SUPPORT
END_NAMESPACE( uLib )
#endif//def HAVE_STRUCTURED_EH
// EOF