Threading.h 17.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630
/*===================== begin_copyright_notice ==================================

Copyright (c) 2017 Intel Corporation

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


======================= end_copyright_notice ==================================*/

#pragma once

#ifdef ISTDLIB_MT
#ifdef WIN32_NO_STATUS
#undef WIN32_NO_STATUS
#include <ntstatus.h>
#define WIN32_NO_STATUS
#endif
#endif

#ifdef _WIN32
#   include "types.h"
#   include <process.h>
#   include <malloc.h>
#endif // _WIN32

namespace iSTD
{

#ifdef _WIN32

/*****************************************************************************\
    Critical Section types
\*****************************************************************************/
#ifdef ISTDLIB_MT
#define DECL_CRITICAL_SECTION(x)    CRITICAL_SECTION x
#define INIT_CRITICAL_SECTION(x)    ::InitializeCriticalSection( &(x) )
#define DELETE_CRITICAL_SECTION(x)  ::DeleteCriticalSection( &(x) )
#define ENTER_CRITICAL_SECTION(x)   ::EnterCriticalSection( &(x) )
#define LEAVE_CRITICAL_SECTION(x)   ::LeaveCriticalSection( &(x) )
#else
#define DECL_CRITICAL_SECTION(x)
#define INIT_CRITICAL_SECTION(x)
#define DELETE_CRITICAL_SECTION(x)
#define ENTER_CRITICAL_SECTION(x)
#define LEAVE_CRITICAL_SECTION(x)
#endif

/*****************************************************************************\
    Critical Section debug
\*****************************************************************************/
// The following macros are used to allow synchronizing a function
// to debug multithreading issues due to re-entrancy
#define ENABLE_THREADED_FUNCTION_SYNC   FALSE

#if defined(ISTDLIB_MT) && ENABLE_THREADED_FUNCTION_SYNC

// Structure to store data
struct THREADED_FUNCTION_DATA
{
    // switch to enable\disable synchronizing a function to debug
    // possible threading issues. intended to be toggled manually
    // using the debugger. always disabled by default.
    bool    IsEnabled;

    // critical section data to synchronize function
    DECL_CRITICAL_SECTION( CS );

    // default constructor to initialize data
    THREADED_FUNCTION_DATA()
    {
        IsEnabled = false;
        INIT_CRITICAL_SECTION( CS );
    };

    // default destructor to clean-up data
    ~THREADED_FUNCTION_DATA()
    {
        DELETE_CRITICAL_SECTION( CS );
    };
};

// Macro for entry-point of threaded function
// Each function has a unique (static) enable and critical section
#define THREADED_FUNCTION_ENTER                 \
    static iSTD::THREADED_FUNCTION_DATA sTFD;   \
    if( sTFD.IsEnabled )                        \
    {                                           \
        ENTER_CRITICAL_SECTION( sTFD.CS );      \
    }

// Macro for exit-point of threaded function
#define THREADED_FUNCTION_EXIT                  \
    if( sTFD.IsEnabled )                        \
    {                                           \
        LEAVE_CRITICAL_SECTION( sTFD.CS );      \
    }

#else

#define THREADED_FUNCTION_ENTER
#define THREADED_FUNCTION_EXIT

#endif

/*****************************************************************************\
    Mutex debug
\*****************************************************************************/
// The following macros are used to check that classes\functions that are not
// re-entrant, are never executed concurently for a single instance
#define ENABLE_DEBUG_MUTEX  FALSE

#if defined(ISTDLIB_MT) && ENABLE_DEBUG_MUTEX

// Structure to store data needed by the debug mutex macros
// 1) a mutex handle to ensure only a single thread exists between Acquire and Release
// 2) a counter for the number of threads trying to enter
struct DEBUG_MUTEX_DATA
{
    HANDLE  Mutex;
    (unsigned __int64*) pCounter;
};

// Declare the data structure
#define DECL_DEBUG_MUTEX(x)     iSTD::DEBUG_MUTEX_DATA  x

// Initialize the debug mutex data
// Read Access counter is x.pCounter[0]
// Write Access counter is x.pCounter[1]
#define INIT_DEBUG_MUTEX(x)                                         \
{                                                                   \
    x.Mutex = ::CreateMutex( NULL, FALSE, NULL );                   \
    x.pCounter = (unsigned __int64*)::_aligned_malloc(              \
        2 * sizeof(unsigned __int64), sizeof(unsigned __int64) );   \
    x.pCounter[0] = 0;                                              \
    x.pCounter[1] = 0;                                              \
}

// Clean-up the debug mutex data
#define DELETE_DEBUG_MUTEX(x)                                       \
{                                                                   \
    ::CloseHandle( x.Mutex );                                       \
    ::_aligned_free( x.pCounter );                                  \
}

// Increment the counter of the number of threads entering with read access
// Acquire the mutex and break if another thread is waiting for write access
#define ACQUIRE_DEBUG_MUTEX_READ(x)                                  \
{                                                                    \
    ::InterlockedIncrement( (unsigned __int64*)&( x.pCounter[0] ) ); \
    while( WAIT_OBJECT_0 != ::WaitForSingleObject( x.Mutex, 1 ) )    \
        if ( 0 != ::InterlockedOr( (unsigned __int64*)&( x.pCounter[1] ), 0 ) ) \
            __debugbreak();                                              \
}

// Break if there is another thread waiting for write access
// Decrement read access counter
// Release the mutex
#define RELEASE_DEBUG_MUTEX_READ(x)                                  \
{                                                                    \
    if( 0 != ::InterlockedOr( (unsigned __int64*)&( x.pCounter[1] ), 0 ) ) \
        __debugbreak();                                              \
    ::InterlockedDecrement( (unsigned __int64*)&( x.pCounter[0] ) ); \
    ::ReleaseMutex( x.Mutex );                                       \
}

// Increment the counter of the number of threads entering with write access
// Acquire the mutex and break if another thread owns the mutex
#define ACQUIRE_DEBUG_MUTEX_WRITE(x)                                 \
{                                                                    \
    ::InterlockedIncrement( (unsigned __int64*)&( x.pCounter[1] ) ); \
    while( WAIT_OBJECT_0 != ::WaitForSingleObject( x.Mutex, 1 ) )    \
        __debugbreak();                                              \
}

// Break if there is another thread waiting for read access
// Decrement the counter and break if there is another thread waiting for write access
// Release the mutex
#define RELEASE_DEBUG_MUTEX_WRITE(x)                                 \
{                                                                    \
    if( 0 != ::InterlockedOr( (unsigned __int64*)&( x.pCounter[0] ), 0 ) ) \
        __debugbreak();                                              \
    if( 0 != ::InterlockedDecrement( (unsigned __int64*)&( x.pCounter[1] ) ) ) \
        __debugbreak();                                              \
    ::ReleaseMutex( x.Mutex );                                       \
}

#else
#define DECL_DEBUG_MUTEX(x)
#define INIT_DEBUG_MUTEX(x)
#define DELETE_DEBUG_MUTEX(x)
#define ACQUIRE_DEBUG_MUTEX_READ(x)
#define RELEASE_DEBUG_MUTEX_READ(x)
#define ACQUIRE_DEBUG_MUTEX_WRITE(x)
#define RELEASE_DEBUG_MUTEX_WRITE(x)
#endif

#ifdef ISTDLIB_MT

/*****************************************************************************\
    Thread Management types
\*****************************************************************************/
// These are heavy-weight threads; consider using Thread-Pools instead
#define THREAD_ARGUMENT     void*
typedef unsigned int (__stdcall *THREAD_FUNCTION)( THREAD_ARGUMENT );

#ifdef ISTDLIB_MT
#define THREAD_HANDLE       HANDLE
#else
struct THREAD_DATA
{
    THREAD_FUNCTION     func;
    THREAD_ARGUMENT     arg;
};
#define THREAD_HANDLE       THREAD_DATA*
#endif

/*****************************************************************************\
Function:
    CreateThreads

Input:
    const DWORD numThreads - number of threads to create
    THREAD_FUNCTION func - pointer to function to execute
    THREAD_ARGUMENT* args - array of per-thread arguments

Output:
    THREAD_HANDLE* threads - array of per-thread handles
    THREAD_HANDLE* beginEvents - array of per-thread events to signal the
        thread to begin
    THREAD_HANDLE* endEvents - array of per-thread events the thread sets
        when complete
    HRESULT

\*****************************************************************************/
inline HRESULT CreateThreads(
    const DWORD numThreads,
    THREAD_FUNCTION func,
    THREAD_ARGUMENT* args,
    THREAD_HANDLE* threads,
    THREAD_HANDLE* beginEvents,
    THREAD_HANDLE* endEvents )
{
    HRESULT hr = S_OK;

    for( DWORD i = 0; i < numThreads; ++i )
    {
#ifdef ISTDLIB_MT

        beginEvents[i] = ::CreateEvent( NULL, FALSE, FALSE, NULL );
        endEvents[i] = ::CreateEvent( NULL, FALSE, FALSE, NULL );

        threads[i] = ( THREAD_HANDLE )::_beginthreadex(
            NULL,
            0,
            func,
            args[i],
            CREATE_SUSPENDED,
            NULL );

        if( threads[i] )
        {
            ::ResumeThread( threads[i] );
        }
        else
        {
            hr = E_FAIL;
        }

#else

        threads[i] = (THREAD_DATA*)malloc( sizeof(THREAD_DATA) );

        if( threads[i] )
        {
            threads[i]->func = func;
            threads[i]->arg = args[i];

            beginEvents[i] = threads[i];
            endEvents[i] = NULL;
        }
        else
        {
            hr = E_FAIL;
        }

#endif
    }

    return hr;
}

/*****************************************************************************\
    StartThreads
\*****************************************************************************/
inline void StartThreads(
    const DWORD numThreads,
    THREAD_HANDLE* beginEvents )
{
    for( DWORD i = 0; i < numThreads; ++i )
    {
#ifdef ISTDLIB_MT

        ::SetEvent( beginEvents[i] );

#else

        beginEvents[i]->func( beginEvents[i]->arg );

#endif
    }
}

/*****************************************************************************\
    WaitForThreads
\*****************************************************************************/
inline void WaitForThreads(
    const DWORD numThreads,
    THREAD_HANDLE* endEvents )
{
#ifdef ISTDLIB_MT

#ifdef _DEBUG

    // deadlock detection
    DWORD result = 0;
    do
    {
        result = ::WaitForMultipleObjects(
            numThreads,
            endEvents,
            TRUE,
            1000 );
        result &= 0xfffffff0;
        ASSERT( WAIT_OBJECT_0 == result );
    }
    while( WAIT_OBJECT_0 != result );

#else

    ::WaitForMultipleObjects(
        numThreads,
        endEvents,
        TRUE,
        INFINITE );

#endif

#endif
}

/*****************************************************************************\
    DeleteThreads
\*****************************************************************************/
inline void DeleteThreads(
    const DWORD numThreads,
    THREAD_HANDLE* threads,
    THREAD_HANDLE* beginEvents,
    THREAD_HANDLE* endEvents )
{
    for( DWORD i = 0; i < numThreads; ++i )
    {
#ifdef ISTDLIB_MT

        ::CloseHandle( threads[i] );
        ::CloseHandle( endEvents[i] );
        ::CloseHandle( beginEvents[i] );

#else

        free( threads[i] );
        threads[i] = NULL;
        endEvents[i] = NULL;
        beginEvents[i] = NULL;

#endif
    }
}

/*****************************************************************************\
    Thread-Pool Management types
\*****************************************************************************/
#if defined(ISTDLIB_MT) && (_WIN32_WINNT >= 0x0600)
// Minimum supported client: Windows Vista (_WIN32_WINNT_VISTA = 0x0600)

/*****************************************************************************\

Function:
    CreateThreadPool

Description:
    Creates a thread pool

Input:
    PTP_CALLBACK_ENVIRON ptrPoolEnv - pointer to storage where thread pool
        environment will be stored
    DWORD minThreads - minimum number of requested threads in the thread pool.
    DWORD maxThreads - maximum number of requested threads in the thread pool.

Output:
    BOOL - Success or Fail

Notes:
    Client is responsible for management of PTP_CALLBACK_ENVIRON memory

\*****************************************************************************/
inline BOOL CreateThreadPool(
    PTP_CALLBACK_ENVIRON ptrPoolEnv,
    const DWORD minThreads,
    const DWORD maxThreads )
{
    if( ptrPoolEnv )
    {
        InitializeThreadpoolEnvironment( ptrPoolEnv );

        PTP_POOL ptrPool = CreateThreadpool( NULL );
        if( ptrPool )
        {
            SetThreadpoolThreadMinimum( ptrPool, minThreads );
            SetThreadpoolThreadMaximum( ptrPool, maxThreads );

            SetThreadpoolCallbackRunsLong( ptrPoolEnv );
            SetThreadpoolCallbackPool( ptrPoolEnv, ptrPool );
            return TRUE;
        }
    }
    return FALSE;
}

/*****************************************************************************\

Function:
    CreateThreadPool

Description:
    Creates a thread pool

Input:
    PTP_CALLBACK_ENVIRON ptrPoolEnv - pointer to storage where thread pool 
        environment will be stored

Output:
    BOOL - Success or Fail

Notes:
    Client is responsible for management of PTP_CALLBACK_ENVIRON memory

\*****************************************************************************/
inline BOOL CreateThreadPool(
    PTP_CALLBACK_ENVIRON ptrPoolEnv )
{
    SYSTEM_INFO si = { 0 };
    ::GetSystemInfo( &si );
    return CreateThreadPool( ptrPoolEnv, si.dwNumberOfProcessors, si.dwNumberOfProcessors );
}

/*****************************************************************************\

Function:
    DeleteThreadPool

Description:
    Deletes a thread pool

Input:
    PTP_CALLBACK_ENVIRON ptrPoolEnv - pointer to storage where thread pool
        environment is stored

Output:
    none

Notes:
    Client is responsible for management of PTP_CALLBACK_ENVIRON memory

\*****************************************************************************/
inline void DeleteThreadPool(
    PTP_CALLBACK_ENVIRON ptrPoolEnv )
{
    if( ptrPoolEnv )
    {
        if( ptrPoolEnv->Pool )
        {
            CloseThreadpool( ptrPoolEnv->Pool );
        }
    }
}

/*****************************************************************************\

Function:
    CreateThreadPoolWork

Description:
    Creates a thread pool work item

Input:
    PTP_WORK_CALLBACK pWorkFunc - pointer to function to add to thread pool
    PVOID pWorkData - optional data to pass to function
    PTP_CALLBACK_ENVIRON ptrPoolEnv - thread pool environment

Output:
    PTP_WORK - pointer to work item

\*****************************************************************************/
inline PTP_WORK CreateThreadPoolWork(
    PTP_WORK_CALLBACK pWorkFunc,
    PVOID pWorkData,
    PTP_CALLBACK_ENVIRON ptrPoolEnv )
{
    return CreateThreadpoolWork( pWorkFunc, pWorkData, ptrPoolEnv );
}

/*****************************************************************************\

Function:
    SubmitThreadPoolWork

Description:
   Submits a thread pool work item to the thread pool

Input:
    PTP_WORK - pointer to work item

Output:
    none

\*****************************************************************************/
inline void SubmitThreadPoolWork(
    PTP_WORK pWorkItem )
{
    if( pWorkItem )
    {
        SubmitThreadpoolWork( pWorkItem );
    }
}

/*****************************************************************************\

Function:
    WaitForThreadPoolWork

Description:
    Waits for the thread pool work item to complete

Input:
    PTP_WORK ptrWork - pointer to work item

Output:
    none

\*****************************************************************************/
inline void WaitForThreadPoolWork(
    PTP_WORK ptrWork )
{
    if( ptrWork )
    {
        WaitForThreadpoolWorkCallbacks( ptrWork, FALSE );
    }
}

/*****************************************************************************\

Function:
    DeleteThreadPoolWork

Description:
    Deletes the thread pool work item to complete

Input:
    PTP_WORK ptrWork - pointer to work item

Output:
    none

\*****************************************************************************/
inline void DeleteThreadPoolWork(
    PTP_WORK& ptrWork )
{
    if( ptrWork )
    {
        CloseThreadpoolWork( ptrWork );
        ptrWork = NULL;
    }
}

#endif //defined(ISTDLIB_MT) && (_WIN32_WINNT >= 0x0600)

#endif //ISTDLIB_MT

#else   // _WIN32

#define THREADED_FUNCTION_ENTER
#define THREADED_FUNCTION_EXIT

#define DECL_CRITICAL_SECTION(x)
#define INIT_CRITICAL_SECTION(x)
#define DELETE_CRITICAL_SECTION(x)
#define ENTER_CRITICAL_SECTION(x)
#define LEAVE_CRITICAL_SECTION(x)

#define DECL_DEBUG_MUTEX(x)
#define INIT_DEBUG_MUTEX(x)
#define DELETE_DEBUG_MUTEX(x)
#define ACQUIRE_DEBUG_MUTEX_READ(x)
#define RELEASE_DEBUG_MUTEX_READ(x)
#define ACQUIRE_DEBUG_MUTEX_WRITE(x)
#define RELEASE_DEBUG_MUTEX_WRITE(x)

#endif  // _WIN32




} // iSTD