concrtrm.h

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

        ///     to a notification event in the Resource Manager. On a user-mode schedulable (UMS) thread scheduler, this indicates that items have
        ///     appeared on the scheduler's completion list, and the scheduler is required to handle them.
        /// </returns>
        /// <remarks>
        ///     Use this method to temporarily stop executing a virtual processor root when you cannot find any work in your scheduler.
        ///     A call to the <c>Deactivate</c> method must originate from within the <c>Dispatch</c> method of the execution context that
        ///     the virtual processor root was last activated with. In other words, the thread proxy invoking the <c>Deactivate</c> method
        ///     must be the one that is currently executing on the virtual processor root. Calling the method on a virtual processor
        ///     root you are not executing on could result in undefined behavior.
        ///     <para>A deactivated virtual processor root may be woken up with a call to the <c>Activate</c> method, with the same
        ///     argument that was passed in to the <c>Deactivate</c> method. The scheduler is responsible for ensuring that calls to the <c>Activate</c>
        ///     and <c>Deactivate</c> methods are paired, but they are not required to be received in a specific order. The Resource
        ///     Manager can handle receiving a call to the <c>Activate</c> method before it receives a call to the <c>Deactivate</c> method it was
        ///     meant for.</para>
        ///     <para>If a virtual processor root awakens and the return value from the <c>Deactivate</c> method is the value <c>false</c>, the scheduler
        ///     should query the UMS completion list via the <c>IUMSCompletionList::GetUnblockNotifications</c> method, act on that information, and
        ///     then subsequently call the <c>Deactivate</c> method again.  This should be repeated until such time as the <c>Deactivate</c> method returns
        ///     the value <c>true</c>.</para>
        ///     <para><c>invalid_argument</c> is thrown if the argument <paramref name="pContext"/> has the value <c>NULL</c>.</para>
        ///     <para><c>invalid_operation</c> is thrown if the virtual processor root has never been activated, or the argument <paramref name="pContext"/>
        ///     does not represent the execution context that was most recently dispatched by this virtual processor root.</para>
        ///     <para>The act of deactivating a virtual processor root decreases the subscription level of the underlying hardware thread by one.  For
        ///     more information on subscription levels, see <see cref="IExecutionResource::CurrentSubscriptionLevel Method">
        ///     IExecutionResource::CurrentSubscriptionLevel</see>.</para>
        /// </remarks>
        /// <seealso cref="IVirtualProcessorRoot::Activate Method"/>
        /// <seealso cref="IExecutionResource::CurrentSubscriptionLevel Method"/>
        /// <seealso cref="IUMSCompletionList::GetUnblockNotifications Method"/>
        /**/
        virtual bool Deactivate(IExecutionContext * pContext) =0;

        /// <summary>
        ///     Causes data stored in the memory hierarchy of individual processors to become visible to all processors on the system.
        ///     It ensures that a full memory fence has been executed on all processors before the method returns.
        /// </summary>
        /// <param name="pContext">
        ///     The context which is currently being dispatched by this virtual processor root.
        /// </param>
        /// <remarks>
        ///     You may find this method useful when you want to synchronize deactivation of a virtual processor root with the addition of new work into
        ///     the scheduler. For performance reasons, you may decide to add work items to your scheduler without executing a memory barrier, which
        ///     means work items added by a thread executing on one processor are not immediately visible to all other processors. By using this method
        ///     in conjunction with the <c>Deactivate</c> method you can ensure that your scheduler does not deactivate all its virtual processor
        ///     roots while work items exist in your scheduler's collections.
        ///     <para> A call to the <c>EnsureAllTasksVisibleThe</c> method must originate from within the <c>Dispatch</c> method of the execution
        ///     context that the virtual processor root was last activated with. In other words, the thread proxy invoking the <c>EnsureAllTasksVisible</c>
        ///     method must be the one that is currently executing on the virtual processor root. Calling the method on a virtual processor
        ///     root you are not executing on could result in undefined behavior.</para>
        ///     <para><c>invalid_argument</c> is thrown if the argument <paramref name="pContext"/> has the value <c>NULL</c>.</para>
        ///     <para><c>invalid_operation</c> is thrown if the virtual processor root has never been activated, or the argument <paramref name="pContext"/>
        ///     does not represent the execution context that was most recently dispatched by this virtual processor root.</para>
        /// </remarks>
        /// <seealso cref="IVirtualProcessorRoot::Deactivate Method"/>
        /**/
        virtual void EnsureAllTasksVisible(IExecutionContext *pContext) =0;
    };

    /// <summary>
    ///     An interface to an abstraction of a work scheduler. The Concurrency Runtime's Resource Manager uses this interface to communicate with work
    ///     schedulers.
    /// </summary>
    /// <remarks>
    ///     If you are implementing a custom scheduler that communicates with the Resource Manager, you should provide an implementation of the
    ///     <c>IScheduler</c> interface. This 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.
    /// </remarks>
    /// <seealso cref="PolicyElementKey Enumeration"/>
    /// <seealso cref="SchedulerPolicy Class"/>
    /// <seealso cref="IExecutionContext Structure"/>
    /// <seealso cref="IThreadProxy Structure"/>
    /// <seealso cref="IVirtualProcessorRoot Structure"/>
    /// <seealso cref="IResourceManager Structure"/>
    /**/
    struct IScheduler
    {
        /// <summary>
        ///     Returns a unique identifier for the scheduler.
        /// </summary>
        /// <returns>
        ///     A unique integer identifier.
        /// </returns>
        /// <remarks>
        ///     You should use the <see cref="GetSchedulerId Function">GetSchedulerId</see> function to obtain a unique identifier for the object
        ///     that implements the <c>IScheduler</c> interface, before you use the interface as a parameter to methods supplied by the Resource Manager.
        ///     You are expected to return the same identifier when the <c>GetId</c> function is invoked. <para> An identifier obtained from a different
        ///     source could result in undefined behavior.</para>
        /// </remarks>
        /**/
        virtual unsigned int GetId() const =0;

        /// <summary>
        ///     Provides information related to task arrival and completion rates, and change in queue length for a scheduler.
        /// </summary>
        /// <param name="pTaskCompletionRate">
        ///     The number of tasks that have been completed by the scheduler since the last call to this method.
        /// </param>
        /// <param name="pTaskArrivalRate">
        ///     The number of tasks that have arrived in the scheduler since the last call to this method.
        /// </param>
        /// <param name="pNumberOfTasksEnqueued">
        ///     The total number of tasks in all scheduler queues.
        /// </param>
        /// <remarks>
        ///     This method is invoked by the Resource Manager in order to gather statistics for a scheduler.  The statistics gathered here
        ///     will be used to drive dynamic feedback algorithms to determine when it is appropriate to assign more resources to
        ///     the scheduler and when to take resources away.  The values provided by the scheduler can be optimistic and do not necessarily
        ///     have to reflect the current count accurately.
        ///     <para> You should implement this method if you want the Resource Manager to use feedback about task arrival, etc. to determine
        ///     how to balance resource between your scheduler and other schedulers registered with the Resource Manager. If you choose not to
        ///     gather statistics, you can set the policy key <c>DynamicProgressFeedback</c> to the value <c>DynamicProgressFeedbackDisabled</c>
        ///     in your scheduler's policy, and the Resource Manager will not invoke this method on your scheduler.</para>
        ///     <para>In the absence of statistical information, the Resource Manager will use hardware thread subscription levels to make
        ///     resource allocation and migration decisions. For more information on subscription levels, see
        ///     <see cref="IExecutionResource::CurrentSubscriptionLevel Method"> IExecutionResource::CurrentSubscriptionLevel</see>.</para>
        /// </remarks>
        /// <seealso cref="PolicyElementKey Enumeration"/>
        /// <seealso cref="IExecutionResource::CurrentSubscriptionLevel Method"/>
        /**/
        virtual void Statistics(unsigned int * pTaskCompletionRate, unsigned int * pTaskArrivalRate, unsigned int * pNumberOfTasksEnqueued) =0;

        /// <summary>
        ///     Returns a copy of the scheduler's policy. For more information on scheduler policies, see <see cref="SchedulerPolicy Class">
        ///     SchedulerPolicy</see>.
        /// </summary>
        /// <returns>
        ///     A copy of the scheduler's policy.
        /// </returns>
        /// <seealso cref="SchedulerPolicy Class"/>
        /**/
        virtual SchedulerPolicy GetPolicy() const =0;

        /// <summary>
        ///     Provides a scheduler with a set of virtual processor roots for its use. Each <c>IVirtualProcessorRoot</c> interface represents
        ///     the right to execute a single thread that can perform work on behalf of the scheduler.
        /// </summary>
        /// <param name="ppVirtualProcessorRoots">
        ///     An array of <c>IVirtualProcessorRoot</c> interfaces representing the virtual processor roots being added to the scheduler.
        /// </param>
        /// <param name="count">
        ///     The number of <c>IVirtualProcessorRoot</c> interfaces in the array.
        /// </param>
        /// <remarks>
        ///     The Resource Manager invokes the <c>AddVirtualProcessor</c> method to grant an initial set of virtual processor roots to
        ///     a scheduler. It could also invoke the method to add virtual processor roots to the scheduler when it rebalances resources
        ///     among schedulers.
        /// </remarks>
        /// <seealso cref="IVirtualProcessorRoot Structure"/>
        /// <seealso cref="IScheduler::RemoveVirtualProcessors Method"/>
        /**/
        virtual void AddVirtualProcessors(IVirtualProcessorRoot ** ppVirtualProcessorRoots, unsigned int count) =0;

        /// <summary>
        ///     Initiates the removal of virtual processor roots that were previously allocated to this scheduler.
        /// </summary>
        /// <param name="ppVirtualProcessorRoots">
        ///     An array of <c>IVirtualProcessorRoot</c> interfaces representing the virtual processor roots to be removed.
        /// </param>
        /// <param name="count">
        ///     The number of <c>IVirtualProcessorRoot</c> interfaces in the array.
        /// </param>
        /// <remarks>
        ///     The Resource Manager invokes the <c>RemoveVirtualProcessors</c> method to take back a set of virtual processor roots from
        ///     a scheduler. The scheduler is expected to invoke the <see cref="IExecutionResource::Remove Method">Remove</see> method on each
        ///     interface when it is done with the virtual processor roots. Do not use an <c>IVirtualProcessorRoot</c> interface once you have
        ///     invoked the <c>Remove</c> method on it.
        ///     <para>The parameter <paramref name="ppVirtualProcessorRoots"/> points to an array of interfaces. Among the set of virtual processor
        ///     roots to be removed, the roots have never been activated can be returned immediately using the <c>Remove</c> method.
        ///     The roots that have been activated and are either executing work, or have been deactivated and are waiting for work to arrive, should be
        ///     returned asynchronously. The scheduler must make every attempt to remove the virtual processor root as quickly as possible.
        ///     Delaying removal of the virtual processor roots may result in unintentional oversubscription within the scheduler.</para>
        /// </remarks>
        /// <seealso cref="IVirtualProcessorRoot Structure"/>
        /// <seealso cref="IScheduler::RemoveVirtualProcessors Method"/>
        /**/
        virtual void RemoveVirtualProcessors(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 not being used by other schedulers.
        /// </summary>
        /// <param name="ppVirtualProcessorRoots">
        ///     An array of <c>IVirtualProcessorRoot</c> interfaces associated with hardware threads on which other schedulers have become idle.
        /// </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