concrtrm.h

Go to the documentation of this file.

/***
* ==++==
*
* Copyright (c) Microsoft Corporation.  All rights reserved.
*
* ==--==
* =+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
*
* concrtrm.h
*
* Main public header file for ConcRT's Resource Manager. This is the only header file a client
* must include to build atop the resource manager.
*
* The core runtime, the Agents and Message Blocks Library, and the Parallel Patterns Library (PPL)
* are defined in different header files.
* =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
****/

#pragma once

#include <crtdefs.h>

#if !(defined (_M_X64) || defined (_M_IX86) || defined (_M_ARM) || defined (_M_ARM64))
    #error ERROR: Concurrency Runtime is supported only on X64, X86, ARM, and ARM64 architectures.
#endif  /* !(defined (_M_X64) || defined (_M_IX86) || defined (_M_ARM) || defined (_M_ARM64)) */

#if defined (_M_CEE)
    #error ERROR: Concurrency Runtime is not supported when compiling /clr.
#endif  /* defined (_M_CEE) */

#ifndef __cplusplus
    #error ERROR: Concurrency Runtime is supported only for C++.
#endif  /* __cplusplus */

#pragma pack(push,_CRT_PACKING)


namespace Concurrency
{
#ifdef _CRT_USE_WINAPI_FAMILY_DESKTOP_APP
    //
    // Forward Declarations:
    //
    struct IScheduler;
    struct IThreadProxy;
    class SchedulerPolicy;

    
    enum SwitchingProxyState
    {
        
        Idle,

        
        Blocking,

        
        Nesting
    };

    
    struct DispatchState
    {
        
        DispatchState() : m_dispatchStateSize(sizeof(DispatchState)), m_fIsPreviousContextAsynchronouslyBlocked(0), m_reserved(0)
        {
        }

        
        unsigned long m_dispatchStateSize;

        
        unsigned int  m_fIsPreviousContextAsynchronouslyBlocked : 1;

        
        unsigned int  m_reserved : 31;
    };

    
    struct IExecutionContext
    {
        
        virtual unsigned int GetId() const =0;

        
        virtual IScheduler * GetScheduler() =0;

        
        virtual IThreadProxy * GetProxy() =0;

        
        virtual void SetProxy(_Inout_ IThreadProxy * pThreadProxy) =0;

        
        virtual void Dispatch(_Inout_ DispatchState * pDispatchState) =0;
    };

    
    struct IThreadProxy
    {
        
        virtual unsigned int GetId() const =0;

        
        virtual void SwitchTo(_Inout_ IExecutionContext * pContext, SwitchingProxyState switchState) =0;

        
        virtual void SwitchOut(SwitchingProxyState switchState = Blocking) =0;

        
        virtual void YieldToSystem() = 0;
    };

    
    enum CriticalRegionType
    {
        
        OutsideCriticalRegion,

        
        InsideCriticalRegion,

        
        InsideHyperCriticalRegion
    };

    
    struct IUMSThreadProxy : public IThreadProxy
    {
        
        virtual int EnterCriticalRegion() =0;

        
        virtual int ExitCriticalRegion() =0;

        
        virtual int EnterHyperCriticalRegion() =0;

        
        virtual int ExitHyperCriticalRegion() =0;

        
        virtual CriticalRegionType GetCriticalRegionType() const =0;
    };

    
    struct IExecutionResource
    {
        
        virtual unsigned int GetNodeId() const =0;

        
        virtual unsigned int GetExecutionResourceId() const =0;

        
        virtual void Remove(_Inout_ IScheduler * pScheduler) =0;

        
        virtual unsigned int CurrentSubscriptionLevel() const =0;
    };

    
    struct IVirtualProcessorRoot : public IExecutionResource
    {
        
        virtual unsigned int GetId() const =0;

        
        virtual void Activate(_Inout_ IExecutionContext * pContext) =0;

        
        virtual bool Deactivate(_Inout_ IExecutionContext * pContext) =0;

        
        virtual void EnsureAllTasksVisible(_Inout_ IExecutionContext *pContext) =0;
    };

    
    struct IScheduler
    {
        
        virtual unsigned int GetId() const =0;

        
        virtual void Statistics(_Out_ unsigned int * pTaskCompletionRate, _Out_ unsigned int * pTaskArrivalRate, _Out_ unsigned int * pNumberOfTasksEnqueued) =0;

        
        virtual SchedulerPolicy GetPolicy() const =0;

        
        virtual void AddVirtualProcessors(_In_reads_(count) IVirtualProcessorRoot ** ppVirtualProcessorRoots, unsigned int count) =0;

        
        virtual void RemoveVirtualProcessors(_In_reads_(count) IVirtualProcessorRoot ** ppVirtualProcessorRoots, unsigned int count) =0;

        
        virtual void NotifyResourcesExternallyIdle(_In_reads_(count) IVirtualProcessorRoot ** ppVirtualProcessorRoots, unsigned int count) =0;

        
        virtual void NotifyResourcesExternallyBusy(_In_reads_(count) IVirtualProcessorRoot ** ppVirtualProcessorRoots, unsigned int count) =0;
    };

    
    struct IUMSUnblockNotification
    {
        
        virtual IExecutionContext* GetContext() =0;

        
        virtual IUMSUnblockNotification* GetNextUnblockNotification() =0;
    };

    
    struct IUMSCompletionList
    {
        
        virtual IUMSUnblockNotification *GetUnblockNotifications() =0;
    };

    
    struct IUMSScheduler : public IScheduler
    {
        
        virtual void SetCompletionList(_Inout_ IUMSCompletionList * pCompletionList) =0;
    };

    
    struct ISchedulerProxy
    {
        
        virtual IExecutionResource * RequestInitialVirtualProcessors(bool doSubscribeCurrentThread) =0;

        
        virtual void Shutdown() =0;

        
        virtual void BindContext(_Inout_ IExecutionContext * pContext) =0;

        
        virtual void UnbindContext(_Inout_ IExecutionContext * pContext) =0;

        
        virtual IExecutionResource * SubscribeCurrentThread() =0;

        
        virtual IVirtualProcessorRoot * CreateOversubscriber(_Inout_ IExecutionResource * pExecutionResource) =0;
    };

    
    struct ITopologyExecutionResource
    {
        
        virtual ITopologyExecutionResource *GetNext() const =0;

        
        virtual unsigned int GetId() const =0;
    };

    
    struct ITopologyNode
    {
        
        virtual ITopologyNode *GetNext() const =0;

        
        virtual unsigned int GetId() const =0;

        
        virtual unsigned long GetNumaNode() const =0;

        
        virtual unsigned int GetExecutionResourceCount() const =0;

        
        virtual ITopologyExecutionResource *GetFirstExecutionResource() const =0;

    };

    
    const unsigned int CONCRT_RM_VERSION_1 = 0x00010000;

    
    struct IResourceManager
    {
        
        virtual unsigned int Reference() =0;

        
        virtual unsigned int Release() =0;

        
        virtual ISchedulerProxy *RegisterScheduler(_Inout_ IScheduler * pScheduler, unsigned int version) =0;

        
        virtual unsigned int GetAvailableNodeCount() const =0;

        
        virtual ITopologyNode* GetFirstNode() const =0;

        
        virtual void CreateNodeTopology(unsigned int nodeCount, _In_reads_(nodeCount) unsigned int * pCoreCount, _In_reads_opt_(nodeCount) unsigned int ** pNodeDistance, _In_reads_(nodeCount) unsigned int * pProcessorGroups) =0;

        
        enum OSVersion
        {
            
            UnsupportedOS,

            
            XP,

            
            Win2k3,

            
            Vista,

            
            Win7OrLater,

            
            UmsThreadAwareOS,

            
            Win8OrLater
        };
    };

    
    _CONCRTIMP IResourceManager* __cdecl CreateResourceManager();

    
    _CONCRTIMP IResourceManager::OSVersion __cdecl GetOSVersion();

    
    _CONCRTIMP unsigned int __cdecl GetSchedulerId();

    
    _CONCRTIMP unsigned int __cdecl GetExecutionContextId();

    
    _CONCRTIMP unsigned int __cdecl GetProcessorCount();

    
    _CONCRTIMP unsigned int __cdecl GetProcessorNodeCount();
#endif  /* _CRT_USE_WINAPI_FAMILY_DESKTOP_APP */
}

namespace concurrency = ::Concurrency;

#pragma pack(pop)