concrtrm.h

C语言库函数的原型,有用的拿去

        ///     of the subscription other schedulers contribute to. Notifications that resources are externally busy are sent to a scheduler when the external
        ///     subscription level for a hardware thread falls to zero from a previous positive value.</para>
        ///     <para>Notifications via this method are only sent to schedulers that have a policy where the value for the <c>MinConcurrency</c>
        ///     policy key is equal to the value for the <c>MaxConcurrency</c> policy key. For more information on scheduler policies,
        ///     see <see cref="SchedulerPolicy Class">SchedulerPolicy</see>.</para>
        ///     <para>A scheduler that qualifies for notifications gets a set of initial notifications when it is created, informing it whether the
        ///     resources it was just assigned are externally busy or idle.</para>
        /// </remarks>
        /// <seealso cref="IExecutionResource::CurrentSubscriptionLevel Method"/>
        /// <seealso cref="IScheduler::NotifyResourcesExternallyBusy Method"/>
        /**/
        virtual void NotifyResourcesExternallyIdle(IVirtualProcessorRoot ** ppVirtualProcessorRoots, unsigned int count) =0;

        /// <summary>
        ///     Notifies this scheduler that the hardware threads represented by the set of virtual processor roots in the array
        ///     <paramref name="ppVirtualProcessorRoots"/> are now being used by other schedulers.
        /// </summary>
        /// <param name="ppVirtualProcessorRoots">
        ///     An array of <c>IVirtualProcessorRoot</c> interfaces associated with the hardware threads on which other schedulers have become busy.
        /// </param>
        /// <param name="count">
        ///     The number of <c>IVirtualProcessorRoot</c> interfaces in the array.
        /// </param>
        /// <remarks>
        ///     It is possible for a particular hardware thread to be assigned to multiple schedulers at the same time. One reason for this could be
        ///     that there are not enough hardware threads on the system to satisfy the minimum concurrency for all schedulers, without sharing resources.
        ///     Another possibility is that resources are temporarily assigned to other schedulers when the owning scheduler is not using them, by way of
        ///     all its virtual processor roots on that hardware thread being deactivated.
        ///     <para>The subscription level of a hardware thread is denoted by the number of subscribed threads and activated virtual processor roots associated
        ///     with that hardware thread. From a particular scheduler's point of view, the external subscription level of a hardware thread is the portion
        ///     of the subscription other schedulers contribute to. Notifications that resources are externally busy are sent to a scheduler when the external
        ///     subscription level for a hardware thread moves from zero into positive territory.</para>
        ///     <para>Notifications via this method are only sent to schedulers that have a policy where the value for the <c>MinConcurrency</c>
        ///     policy key is equal to the value for the <c>MaxConcurrency</c> policy key. For more information on scheduler policies,
        ///     see <see cref="SchedulerPolicy Class">SchedulerPolicy</see>.</para>
        ///     <para>A scheduler that qualifies for notifications gets a set of initial notifications when it is created, informing it whether the
        ///     resources it was just assigned are externally busy or idle.</para>
        /// </remarks>
        /// <seealso cref="IExecutionResource::CurrentSubscriptionLevel Method"/>
        /// <seealso cref="IScheduler::NotifyResourcesExternallyIdle Method"/>
        /**/
        virtual void NotifyResourcesExternallyBusy(IVirtualProcessorRoot ** ppVirtualProcessorRoots, unsigned int count) =0;
    };

    /// <summary>
    ///     Represents a notification from the Resource Manager that a thread proxy which blocked and triggered a return to the scheduler's
    ///     designated scheduling context has unblocked and is ready to be scheduled. This interface is invalid once the thread proxy's
    ///     associated execution context, returned from the <c>GetContext</c> method, is rescheduled.
    /// </summary>
    /// <seealso cref="IUMSScheduler Structure"/>
    /// <seealso cref="IUMSCompletionList Structure"/>
    /**/
    struct IUMSUnblockNotification
    {
        /// <summary>
        ///     Returns the <c>IExecutionContext</c> interface for the execution context associated with the thread proxy which has
        ///     unblocked.  Once this method returns and the underlying execution context has been rescheduled via a call to the
        ///     <c>IThreadProxy::SwitchTo</c> method, this interface is no longer valid.
        /// </summary>
        /// <returns>
        ///     An <c>IExecutionContext</c> interface for the execution context to a thread proxy which has unblocked.
        /// </returns>
        /**/
        virtual IExecutionContext* GetContext() =0;

        /// <summary>
        ///     Returns the next <c>IUMSUnblockNotification</c> interface in the chain returned from the method
        ///     <c>IUMSCompletionList::GetUnblockNotifications</c>.
        /// </summary>
        /// <returns>
        ///     The next <c>IUMSUnblockNotification</c> interface in the chain returned from the method <c>IUMSCompletionList::GetUnblockNotifications</c>.
        /// </returns>
        /**/
        virtual IUMSUnblockNotification* GetNextUnblockNotification() =0;
    };

    /// <summary>
    ///     Represents a UMS completion list.  When a UMS thread blocks, the scheduler's designated scheduling context is dispatched
    ///     in order to make a decision of what to schedule on the underlying virtual processor root while the original thread is blocked.  When the
    ///     original thread unblocks, the operating system queues it to the completion list which is accessible through this interface.  The scheduler can
    ///     query the completion list on the designated scheduling context or any other place it searches for work.
    /// </summary>
    /// <remarks>
    ///     A scheduler must be extraordinarily careful about what actions are performed after utilizing this interface to dequeue items from the completion
    ///     list.  The items should be placed on the scheduler's list of runnable contexts and be generally accessible as soon as possible.  It is entirely
    ///     possible that one of the dequeued items has been given ownership of an arbitrary lock.  The scheduler can make no arbitrary function calls that may
    ///     block between the call to dequeue items and the placement of those items on a list that can be generally accessed from within the scheduler.
    /// </remarks>
    /// <seealso cref="IUMSScheduler Structure"/>
    /// <seealso cref="IUMSUnblockNotification Structure"/>
    /**/
    struct IUMSCompletionList
    {
        /// <summary>
        ///     Retrieves a chain of <c>IUMSUnblockNotification</c> interfaces representing execution contexts whose associated thread proxies
        ///     have unblocked since the last time this method was invoked.
        /// </summary>
        /// <returns>
        ///     A chain of <c>IUMSUnblockNotification</c> interfaces.
        /// </returns>
        /// <remarks>
        ///     The returned notifications are invalid once the execution contexts are rescheduled.
        /// </remarks>
        /// <seealso cref="IUMSUnblockNotification Structure"/>
        /**/
        virtual IUMSUnblockNotification *GetUnblockNotifications() =0;
    };

    /// <summary>
    ///     An interface to an abstraction of a work scheduler that wants the Concurrency Runtime's Resource Manager to hand it user-mode
    ///     schedulable (UMS) threads. The Resource Manager uses this interface to communicate with UMS thread schedulers. The <c>IUMSScheduler</c> interface
    ///     inherits from the <c>IScheduler</c> interface.
    /// </summary>
    /// <remarks>
    ///     If you are implementing a custom scheduler that communicates with the Resource Manager, and you want UMS threads to be handed to your scheduler
    ///     instead of ordinary Win32 threads, you should provide an implementation of the <c>IUMSScheduler</c> interface. In addition, you should set the
    ///     policy value for the scheduler policy key <c>SchedulerKind</c> to be <c>UmsThreadDefault</c>. If the policy specifies UMS thread, the
    ///     <c>IScheduler</c> interface that is passed as a parameter to the <see cref="IResourceManager::RegisterScheduler Method">IResourceManager::RegisterScheduler
    ///     </see> method must be an <c>IUMSScheduler</c> interface.
    ///     <para>The Resource Manager is able to hand you UMS threads only on operating systems that have the UMS feature. 64-bit operating systems with
    ///     version Windows 7 and higher support UMS threads.  If you create a scheduler policy with the <c>SchedulerKind</c> key set to the value
    ///     <c>UmsThreadDefault</c> and the underlying platform does not support UMS, the value of the <c>SchedulerKind</c> key on that policy will
    ///     be changed to the value <c>ThreadScheduler</c>.  You should always read back this policy value before expecting to receive UMS threads.</para>
    ///     <para> The <c>IUMSScheduler</c> interface is one end of a two-way channel of communication between a scheduler and the Resource Manager.
    ///     The other end is represented by the <c>IResourceManager</c> and <c>ISchedulerProxy</c> interfaces, which are implemented by the Resource Manager.</para>
    /// </remarks>
    /// <seealso cref="PolicyElementKey Enumeration"/>
    /// <seealso cref="IScheduler Structure"/>
    /// <seealso cref="IUMSCompletionList Structure"/>
    /// <seealso cref="IResourceManager Structure"/>
    /**/
    struct IUMSScheduler : public IScheduler
    {
        /// <summary>
        ///     Assigns an <c>IUMSCompletionList</c> interface to a UMS thread scheduler.
        /// </summary>
        /// <param name="pCompletionList">
        ///     The completion list interface for the scheduler.  There is a single list per scheduler.
        /// </param>
        /// <remarks>
        ///     The Resource Manager will invoke this method on a scheduler that specifies it wants UMS threads, after the scheduler has requested an initial
        ///     allocation of resources. The scheduler can use the <c>IUMSCompletionList</c> interface to determine when UMS thread proxies have unblocked.
        ///     It is only valid to access this interface from a thread proxy running on a virtual processor root assigned to the UMS scheduler.
        /// </remarks>
        /// <seealso cref="IScheduler Structure"/>
        /// <seealso cref="IUMSCompletionList Structure"/>
        /**/
        virtual void SetCompletionList(IUMSCompletionList * pCompletionList) =0;
    };

    /// <summary>
    ///     The interface by which schedulers communicate with the Concurrency Runtime's Resource Manager to negotiate resource allocation.
    /// </summary>
    /// <remarks>
    ///     The Resource Manager hands an <c>ISchedulerProxy</c> interface to every scheduler that registers with it using the
    ///     <see cref="IResourceManager::RegisterScheduler Method">IResourceManager::RegisterScheduler</see> method.
    /// </remarks>
    /// <seealso cref="IScheduler Structure"/>
    /// <seealso cref="IThreadProxy Structure"/>
    /// <seealso cref="IVirtualProcessorRoot Structure"/>
    /// <seealso cref="IResourceManager Structure"/>
    /**/
    struct ISchedulerProxy
    {
        /// <summary>
        ///     Requests an initial allocation of virtual processor roots. Every virtual processor root represents the ability to execute one thread
        ///     that can perform work for the scheduler.
        /// </summary>
        /// <param name="doSubscribeCurrentThread">
        ///     Whether to subscribe the current thread and account for it during resource allocation.
        /// </param>
        /// <returns>
        ///     The <c>IExecutionResource</c> interface for the current thread, if the parameter <paramref name="doSubscribeCurrentThread"/> has
        ///     the value <c>true</c>. If the value is <c>false</c>, the method returns <c>NULL</c>.
        /// </returns>
        /// <remarks>
        ///     Before a scheduler executes any work, it should use this method to request virtual processor roots from the Resource Manager. The Resource
        ///     Manager will access the scheduler's policy using <see cref="IScheduler::GetPolicy Method">IScheduler::GetPolicy</see> and use the
        ///     values for the policy keys <c>MinConcurrency</c>, <c>MaxConcurrency</c> and <c>TargetOversubscriptionFactor</c> to determine how many
        ///     hardware threads to assign to the scheduler initially and how many virtual processor roots to create for every hardware thread.
        ///     For more information on how scheduler policies are used to determine a scheduler's initial allocation, see <see cref="PolicyElementKey Enumeration">
        ///     PolicyElementKey</see>.
        ///     <para>The Resource Manager grants resources to a scheduler by calling the method <see cref="IScheduler::AddVirtualProcessors Method">
        ///     IScheduler::AddVirtualProcessors</see> with a list of virtual processor roots. The method is invoked as a callback into the scheduler
        ///     before this method returns.</para>
        ///     <para> If the scheduler requested subscription for the current thread by setting the parameter <paramref name="doSubscribeCurrentThread"/>
        ///     to <c>true</c>, the method returns an <c>IExecutionResource</c> interface. The subscription must be terminated at a later point by using
        ///     the <see cref="IExecutionResource::Remove Method">IExecutionResource::Remove</see> method.</para>
        ///     <para>When determining which hardware threads are selected, the Resource Manager will attempt to optimize for processor node affinity.
        ///     If subscription is requested for the current thread, it is an indication that the current thread intends to participate in the work assigned
        ///     to this scheduler. In such a case, the allocated virtual processors roots are located on the processor node the current thread is executing on,
        ///     if po