task_group — Klasatask_group Class

task_groupKlasa reprezentuje kolekcję równoległych zadań, które mogą być oczekiwane lub anulowane.The task_group class represents a collection of parallel work which can be waited on or canceled.

SkładniaSyntax

class task_group;

Elementy członkowskieMembers

Konstruktory publicznePublic Constructors

NazwaName OpisDescription
task_grouptask_group Przeciążone.Overloaded. Tworzy nowy task_group obiekt.Constructs a new task_group object.
~ task_group destruktor~task_group Destructor Niszczy task_group obiekt.Destroys a task_group object. Oczekiwane jest wywołanie wait run_and_wait metody lub obiektu przed wykonaniem destruktora, chyba że destruktor jest wykonywany jako wynik odwinięcia stosu z powodu wyjątku.You are expected to call the either the wait or run_and_wait method on the object prior to the destructor executing, unless the destructor is executing as the result of stack unwinding due to an exception.

Metody publicznePublic Methods

NazwaName OpisDescription
Anulujcancel W ramach tej grupy zadań najlepszym etapem jest próba anulowania poddrzewa pracy z odblokowanym dostępem.Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Każde zadanie zaplanowane w grupie zadań zostanie anulowane przechodniie, jeśli jest to możliwe.Every task scheduled on the task group will get canceled transitively if possible.
is_cancelingis_canceling Informuje obiekt wywołujący niezależnie od tego, czy grupa zadań jest obecnie w pośrodku anulowania.Informs the caller whether or not the task group is currently in the midst of a cancellation. Nie musi to oznaczać, że cancel Metoda została wywołana na task_group obiekcie (mimo że na pewno kwalifikuje się ta metoda do zwrócenia true ).This does not necessarily indicate that the cancel method was called on the task_group object (although such certainly qualifies this method to return true). Może tak być, że task_group obiekt wykonuje wbudowaną, a grupa zadań została anulowana w drzewie roboczym.It may be the case that the task_group object is executing inline and a task group further up in the work tree was canceled. W takich przypadkach, w których środowisko uruchomieniowe może ustalić przed czasem, gdy anulowanie będzie przepływać przez ten task_group obiekt, true również zostanie zwrócone.In cases such as these where the runtime can determine ahead of time that cancellation will flow through this task_group object, true will be returned as well.
wykonanerun Przeciążone.Overloaded. Planuje zadanie na task_group obiekcie.Schedules a task on the task_group object. Jeśli task_handle obiekt jest przekazaniem jako parametr do run , obiekt wywołujący jest odpowiedzialny za zarządzanie okresem istnienia task_handle obiektu.If a task_handle object is passed as a parameter to run, the caller is responsible for managing the lifetime of the task_handle object. Wersja metody, która pobiera odwołanie do obiektu funkcji jako parametr, obejmuje alokację sterty wewnątrz środowiska uruchomieniowego, co może być wykonane mniej dobrze niż przy użyciu wersji, która pobiera odwołanie do task_handle obiektu.The version of the method that takes a reference to a function object as a parameter involves heap allocation inside the runtime which may be perform less well than using the version that takes a reference to a task_handle object. Wersja, która pobiera parametr _Placement powoduje, że zadanie jest rozdzielone na wykonanie w lokalizacji określonej przez ten parametr.The version which takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter.
run_and_waitrun_and_wait Przeciążone.Overloaded. Planuje uruchamianie zadania w sposób wbudowany w kontekście wywoływania przy użyciu task_group obiektu do obsługi pełnego anulowania.Schedules a task to be run inline on the calling context with the assistance of the task_group object for full cancellation support. Funkcja czeka, aż wszystkie prace na obiekcie zostaną task_group zakończone lub anulowane.The function then waits until all work on the task_group object has either completed or been canceled. Jeśli task_handle obiekt jest przekazaniem jako parametr do run_and_wait , obiekt wywołujący jest odpowiedzialny za zarządzanie okresem istnienia task_handle obiektu.If a task_handle object is passed as a parameter to run_and_wait, the caller is responsible for managing the lifetime of the task_handle object.
trwawait Czeka, aż wszystkie prace na task_group obiekcie zostaną zakończone lub anulowane.Waits until all work on the task_group object has either completed or been canceled.

UwagiRemarks

W przeciwieństwie do mocno ograniczonej structured_task_group klasy Klasa task_group jest znacznie bardziej ogólna konstrukcja.Unlike the heavily restricted structured_task_group class, the task_group class is much more general construct. Nie ma żadnych ograniczeń opisanych przez structured_task_group.It does not have any of the restrictions described by structured_task_group. task_group obiekty mogą być bezpiecznie używane między wątkami i wykorzystane w sposób niezależny.task_group objects may safely be used across threads and utilized in free-form ways. Wadą task_group konstrukcji jest to, że może nie działać, a także structured_task_group konstrukcja dla zadań, które wykonują niewielkie ilości pracy.The disadvantage of the task_group construct is that it may not perform as well as the structured_task_group construct for tasks which perform small amounts of work.

Aby uzyskać więcej informacji, zobacz równoległość zadań.For more information, see Task Parallelism.

Hierarchia dziedziczeniaInheritance Hierarchy

task_group

WymaganiaRequirements

Nagłówek: PPL. hHeader: ppl.h

Przestrzeń nazw: współbieżnośćNamespace: concurrency

Anulujcancel

W ramach tej grupy zadań najlepszym etapem jest próba anulowania poddrzewa pracy z odblokowanym dostępem.Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Każde zadanie zaplanowane w grupie zadań zostanie anulowane przechodniie, jeśli jest to możliwe.Every task scheduled on the task group will get canceled transitively if possible.

void cancel();

UwagiRemarks

Aby uzyskać więcej informacji, zobacz anulowania.For more information, see Cancellation.

is_cancelingis_canceling

Informuje obiekt wywołujący niezależnie od tego, czy grupa zadań jest obecnie w pośrodku anulowania.Informs the caller whether or not the task group is currently in the midst of a cancellation. Nie musi to oznaczać, że cancel Metoda została wywołana na task_group obiekcie (mimo że na pewno kwalifikuje się ta metoda do zwrócenia true ).This does not necessarily indicate that the cancel method was called on the task_group object (although such certainly qualifies this method to return true). Może tak być, że task_group obiekt wykonuje wbudowaną, a grupa zadań została anulowana w drzewie roboczym.It may be the case that the task_group object is executing inline and a task group further up in the work tree was canceled. W takich przypadkach, w których środowisko uruchomieniowe może ustalić przed czasem, gdy anulowanie będzie przepływać przez ten task_group obiekt, true również zostanie zwrócone.In cases such as these where the runtime can determine ahead of time that cancellation will flow through this task_group object, true will be returned as well.

bool is_canceling();

Wartość zwracanaReturn Value

Wskazanie, czy task_group obiekt znajduje się w pośrodku anulowania (lub ma być wkrótce zagwarantowany).An indication of whether the task_group object is in the midst of a cancellation (or is guaranteed to be shortly).

UwagiRemarks

Aby uzyskać więcej informacji, zobacz anulowania.For more information, see Cancellation.

wykonanerun

Planuje zadanie na task_group obiekcie.Schedules a task on the task_group object. Jeśli task_handle obiekt jest przekazaniem jako parametr do run , obiekt wywołujący jest odpowiedzialny za zarządzanie okresem istnienia task_handle obiektu.If a task_handle object is passed as a parameter to run, the caller is responsible for managing the lifetime of the task_handle object. Wersja metody, która pobiera odwołanie do obiektu funkcji jako parametr, obejmuje alokację sterty wewnątrz środowiska uruchomieniowego, co może być wykonane mniej dobrze niż przy użyciu wersji, która pobiera odwołanie do task_handle obiektu.The version of the method that takes a reference to a function object as a parameter involves heap allocation inside the runtime which may be perform less well than using the version that takes a reference to a task_handle object. Wersja, która pobiera parametr _Placement powoduje, że zadanie jest rozdzielone na wykonanie w lokalizacji określonej przez ten parametr.The version which takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter.

template<
   typename _Function
>
void run(
   const _Function& _Func
);

template<
   typename _Function
>
void run(
   const _Function& _Func,
   location& _Placement
);

template<
   typename _Function
>
void run(
   task_handle<_Function>& _Task_handle
);

template<
   typename _Function
>
void run(
   task_handle<_Function>& _Task_handle,
   location& _Placement
);

ParametryParameters

_Function_Function
Typ obiektu funkcji, który zostanie wywołany w celu wykonania treści uchwytu zadania.The type of the function object that will be invoked to execute the body of the task handle.

_Func_Func
Funkcja, która zostanie wywołana w celu wywołania treści zadania.A function which will be called to invoke the body of the task. Może to być wyrażenie lambda lub inny obiekt, który obsługuje wersję operatora wywołania funkcji z podpisem void operator()() .This may be a lambda expression or other object which supports a version of the function call operator with the signature void operator()().

_Placement_Placement
Odwołanie do lokalizacji, w której ma zostać wykonane zadanie reprezentowane przez _Func parametr.A reference to the location where the task represented by the _Func parameter should execute.

_Task_handle_Task_handle
Dojście do zaplanowanych zadań.A handle to the work being scheduled. Należy zauważyć, że obiekt wywołujący odpowiada za okres istnienia tego obiektu.Note that the caller has responsibility for the lifetime of this object. Środowisko uruchomieniowe będzie nadal oczekiwać na żywo do momentu wait run_and_wait wywołania metody lub dla tego task_group obiektu.The runtime will continue to expect it to live until either the wait or run_and_wait method has been called on this task_group object.

UwagiRemarks

Środowisko uruchomieniowe planuje uruchomienie podanej funkcji roboczej w późniejszym czasie, która może być po powrocie funkcji wywołującej.The runtime schedules the provided work function to run at a later time, which can be after the calling function returns. Ta metoda używa obiektu task_handle do przechowywania kopii podanej funkcji służbowej.This method uses a task_handle object to hold a copy of the provided work function. W związku z tym wszelkie zmiany stanu, które występują w obiekcie funkcji przekazywanym do tej metody, nie będą wyświetlane w kopii tego obiektu funkcji.Therefore, any state changes that occur in a function object that you pass to this method will not appear in your copy of that function object. Ponadto należy się upewnić, że okres istnienia wszystkich obiektów przekazywanych przez wskaźnik lub przez odwołanie do funkcji służbowej pozostanie ważny do momentu, gdy funkcja pracy zwróci wartość.In addition, make sure that the lifetime of any objects that you pass by pointer or by reference to the work function remain valid until the work function returns.

Jeśli task_group destruktory jako wynik odwinięcia stosu z wyjątku, nie ma potrzeby zagwarantowania, że wywołanie zostało wykonane do wait run_and_wait metody lub.If the task_group destructs as the result of stack unwinding from an exception, you do not need to guarantee that a call has been made to either the wait or run_and_wait method. W takim przypadku destruktor zostanie odpowiednio anulowany i poczeka na ukończenie zadania reprezentowanego przez _Task_handle parametr.In this case, the destructor will appropriately cancel and wait for the task represented by the _Task_handle parameter to complete.

Metoda zgłasza wyjątek invalid_multiple_scheduling , jeśli dojście zadania przekazanego przez _Task_handle parametr został już zaplanowany do obiektu grupy zadań za pośrednictwem run metody i nie istnieje wywołanie wywołujące do wait run_and_wait metody lub dla tej grupy zadań.The method throws an invalid_multiple_scheduling exception if the task handle given by the _Task_handle parameter has already been scheduled onto a task group object via the run method and there has been no intervening call to either the wait or run_and_wait method on that task group.

run_and_waitrun_and_wait

Planuje uruchamianie zadania w sposób wbudowany w kontekście wywoływania przy użyciu task_group obiektu do obsługi pełnego anulowania.Schedules a task to be run inline on the calling context with the assistance of the task_group object for full cancellation support. Funkcja czeka, aż wszystkie prace na obiekcie zostaną task_group zakończone lub anulowane.The function then waits until all work on the task_group object has either completed or been canceled. Jeśli task_handle obiekt jest przekazaniem jako parametr do run_and_wait , obiekt wywołujący jest odpowiedzialny za zarządzanie okresem istnienia task_handle obiektu.If a task_handle object is passed as a parameter to run_and_wait, the caller is responsible for managing the lifetime of the task_handle object.

template<
   class _Function
>
task_group_status run_and_wait(
   task_handle<_Function>& _Task_handle
);

template<
   class _Function
>
task_group_status run_and_wait(
   const _Function& _Func
);

ParametryParameters

_Function_Function
Typ obiektu funkcji, który zostanie wywołany, aby wykonać treść zadania.The type of the function object that will be invoked to execute the body of the task.

_Task_handle_Task_handle
Dojście do zadania, które zostanie uruchomione w tekście w kontekście wywołującym.A handle to the task which will be run inline on the calling context. Należy zauważyć, że obiekt wywołujący odpowiada za okres istnienia tego obiektu.Note that the caller has responsibility for the lifetime of this object. Środowisko uruchomieniowe będzie nadal oczekiwać na żywo do momentu run_and_wait zakończenia wykonywania metody.The runtime will continue to expect it to live until the run_and_wait method finishes execution.

_Func_Func
Funkcja, która zostanie wywołana w celu wywołania treści pracy.A function which will be called to invoke the body of the work. Może to być wyrażenie lambda lub inny obiekt, który obsługuje wersję operatora wywołania funkcji z podpisem void operator()() .This may be a lambda expression or other object which supports a version of the function call operator with the signature void operator()().

Wartość zwracanaReturn Value

Wskazanie, czy oczekiwano oczekiwania, czy grupa zadań została anulowana z powodu jawnej operacji anulowania lub zgłaszania wyjątku z jednego z jego zadań.An indication of whether the wait was satisfied or the task group was canceled, due to either an explicit cancel operation or an exception being thrown from one of its tasks. Aby uzyskać więcej informacji, zobacz task_group_status.For more information, see task_group_status.

UwagiRemarks

Należy zauważyć, że co najmniej jedno z zadań zaplanowanych do tego task_group obiektu może zostać wykonane w tekście w kontekście wywołującym.Note that one or more of the tasks scheduled to this task_group object may execute inline on the calling context.

Jeśli co najmniej jedno z zadań zaplanowanych dla tego task_group obiektu zgłasza wyjątek, środowisko uruchomieniowe wybierze jeden z tych wyjątków, a następnie propaguje go z wywołania run_and_wait metody.If one or more of the tasks scheduled to this task_group object throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to the run_and_wait method.

Po powrocie z run_and_wait metody na task_group obiekcie środowisko uruchomieniowe resetuje obiekt do stanu czystego, gdzie można go ponownie użyć.Upon return from the run_and_wait method on a task_group object, the runtime resets the object to a clean state where it can be reused. Obejmuje to przypadek, w którym task_group obiekt został anulowany.This includes the case where the task_group object was canceled.

W niewyjątkowej ścieżce wykonywania użytkownik ma mandat do wywołania tej metody lub wait metody przed destruktorem task_group wykonywanym.In the non-exceptional path of execution, you have a mandate to call either this method or the wait method before the destructor of the task_group executes.

task_grouptask_group

Tworzy nowy task_group obiekt.Constructs a new task_group object.

task_group();

task_group(
   cancellation_token _CancellationToken
);

ParametryParameters

_CancellationToken_CancellationToken
Token anulowania, który ma zostać skojarzony z tą grupą zadań.A cancellation token to associate with this task group. Po anulowaniu tokenu grupa zadań zostanie anulowana.The task group will be canceled when the token is canceled.

UwagiRemarks

Konstruktor, który pobiera token anulowania task_group , tworzy, który zostanie anulowany, gdy źródło skojarzone z tokenem zostanie anulowane.The constructor that takes a cancellation token creates a task_group that will be canceled when the source associated with the token is canceled. Dostarczenie jawnego tokenu anulowania spowoduje również wyodrębnienie tej grupy zadań z uczestnictwa w niejawnym anulowaniu z grupy nadrzędnej z innym tokenem lub bez tokenu.Providing an explicit cancellation token also isolates this task group from participating in an implicit cancellation from a parent group with a different token or no token.

~ task_group~task_group

Niszczy task_group obiekt.Destroys a task_group object. Oczekiwane jest wywołanie wait run_and_wait metody lub obiektu przed wykonaniem destruktora, chyba że destruktor jest wykonywany jako wynik odwinięcia stosu z powodu wyjątku.You are expected to call the either the wait or run_and_wait method on the object prior to the destructor executing, unless the destructor is executing as the result of stack unwinding due to an exception.

~task_group();

UwagiRemarks

Jeśli destruktor działa jako wynik normalnego wykonywania (na przykład nie powoduje odwinięcia stosu ze względu na wyjątek), a metody i nie wait run_and_wait zostały wywołane, destruktor może zgłosić wyjątek missing_wait .If the destructor runs as the result of normal execution (for example, not stack unwinding due to an exception) and neither the wait nor run_and_wait methods have been called, the destructor may throw a missing_wait exception.

trwawait

Czeka, aż wszystkie prace na task_group obiekcie zostaną zakończone lub anulowane.Waits until all work on the task_group object has either completed or been canceled.

task_group_status wait();

Wartość zwracanaReturn Value

Wskazanie, czy oczekiwano oczekiwania, czy grupa zadań została anulowana z powodu jawnej operacji anulowania lub zgłaszania wyjątku z jednego z jego zadań.An indication of whether the wait was satisfied or the task group was canceled, due to either an explicit cancel operation or an exception being thrown from one of its tasks. Aby uzyskać więcej informacji, zobacz task_group_status.For more information, see task_group_status.

UwagiRemarks

Należy zauważyć, że co najmniej jedno z zadań zaplanowanych do tego task_group obiektu może zostać wykonane w tekście w kontekście wywołującym.Note that one or more of the tasks scheduled to this task_group object may execute inline on the calling context.

Jeśli co najmniej jedno z zadań zaplanowanych dla tego task_group obiektu zgłasza wyjątek, środowisko uruchomieniowe wybierze jeden z tych wyjątków, a następnie propaguje go z wywołania wait metody.If one or more of the tasks scheduled to this task_group object throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to the wait method.

Wywołanie wait na task_group obiekcie powoduje zresetowanie go do stanu czystego, w którym można go ponownie użyć.Calling wait on a task_group object resets it to a clean state where it can be reused. Obejmuje to przypadek, w którym task_group obiekt został anulowany.This includes the case where the task_group object was canceled.

W niewyjątkowej ścieżce wykonywania użytkownik ma mandat do wywołania tej metody lub run_and_wait metody przed destruktorem task_group wykonywanym.In the non-exceptional path of execution, you have a mandate to call either this method or the run_and_wait method before the destructor of the task_group executes.

Zobacz teżSee also

Przestrzeń nazw współbieżnościconcurrency Namespace
Klasa structured_task_groupstructured_task_group Class
Klasa task_handletask_handle Class