structured_task_group — Klasa
Klasa structured_task_group
reprezentuje wysoce ustrukturyzowaną kolekcję równoległej pracy. Można kolejkować poszczególne zadania równoległe do structured_task_group
obiektu przy użyciu task_handle
obiektów i czekać na ich ukończenie lub anulować grupę zadań przed zakończeniem wykonywania, co spowoduje przerwanie wszystkich zadań, które nie rozpoczęły wykonywania.
Składnia
class structured_task_group;
Elementy członkowskie
Konstruktory publiczne
Nazwa/nazwisko | opis |
---|---|
structured_task_group | Przeciążone. Tworzy nowy structured_task_group obiekt. |
~structured_task_group Destruktor | structured_task_group Niszczy obiekt. Oczekuje się, że wywołasz metodę wait lub run_and_wait na obiekcie przed wykonaniem destruktora, chyba że destruktor wykonuje w wyniku odwijania stosu z powodu wyjątku. |
Metody publiczne
Nazwa/nazwisko | opis |
---|---|
Anuluj | Podejmuje najlepszą próbę anulowania podzadrzewa pracy zakorzenionej w tej grupie zadań. Każde zadanie zaplanowane w grupie zadań zostanie anulowane przechodnio, jeśli jest to możliwe. |
is_canceling | Informuje obiekt wywołujący, czy grupa zadań znajduje się obecnie w trakcie anulowania. Niekoniecznie oznacza to, że cancel metoda została wywołana w structured_task_group obiekcie (chociaż z pewnością kwalifikuje tę metodę do zwrócenia true ). Może się zdarzyć, że structured_task_group obiekt jest wykonywany w tekście, a grupa zadań dalej w drzewie roboczym została anulowana. W takich przypadkach, w których środowisko uruchomieniowe może określić przed upływem czasu, że anulowanie będzie przepływać przez ten structured_task_group obiekt, true zostanie również zwrócone. |
uruchom | Przeciążone. Planuje zadanie w structured_task_group obiekcie . Obiekt wywołujący zarządza okresem istnienia task_handle obiektu przekazanego w parametrze _Task_handle . Wersja, która przyjmuje parametr _Placement powoduje, że zadanie jest stronnicze w kierunku wykonywania w lokalizacji określonej przez ten parametr. |
run_and_wait | Przeciążone. Planuje uruchomienie zadania wbudowanego w kontekście wywołującym z pomocą obiektu w celu zapewnienia pełnej structured_task_group obsługi anulowania. task_handle Jeśli obiekt jest przekazywany jako parametr do run_and_wait obiektu , obiekt wywołujący jest odpowiedzialny za zarządzanie okresem istnienia task_handle obiektu. Następnie funkcja czeka, aż wszystkie prace nad structured_task_group obiektem zostaną ukończone lub anulowane. |
czekać | Czeka, aż wszystkie prace nad ukończeniem structured_task_group lub zostaną anulowane. |
Uwagi
Istnieje wiele poważnych ograniczeń dotyczących użycia structured_task_group
obiektu w celu uzyskania wydajności:
Pojedynczy
structured_task_group
obiekt nie może być używany przez wiele wątków. Wszystkie operacje nastructured_task_group
obiekcie muszą być wykonywane przez wątek, który utworzył obiekt. Dwa wyjątki od tej reguły to funkcjecancel
składowe iis_canceling
. Obiekt może nie znajdować się na liście przechwytywania wyrażenia lambda i być używany w ramach zadania, chyba że zadanie używa jednej z operacji anulowania.Wszystkie zadania zaplanowane do
structured_task_group
obiektu są zaplanowane przy użyciutask_handle
obiektów, które należy jawnie zarządzać okresem istnienia.Wiele grup może być używanych tylko w bezwzględnie zagnieżdżonej kolejności. Jeśli zadeklarowane są dwa
structured_task_group
obiekty, drugi zadeklarowany (wewnętrzny) musi destrukcji przed dowolną metodą z wyjątkiemcancel
lubis_canceling
jest wywoływany na pierwszym (zewnętrznym). Ten warunek ma wartość true zarówno w przypadku zwykłego deklarowania wielustructured_task_group
obiektów w ramach tych samych lub funkcjonalnie zagnieżdżonych zakresów, jak również przypadku zadania, które zostało w kolejce dostructured_task_group
obiektu za pomocąrun
metod lubrun_and_wait
.W przeciwieństwie do klasy ogólnej
task_group
wszystkie stany wstructured_task_group
klasie są końcowe. Po kolejce zadań do grupy i oczekiwaniu na ich ukończenie może nie być ponownie używana ta sama grupa.
Aby uzyskać więcej informacji, zobacz Równoległość zadań.
Hierarchia dziedziczenia
structured_task_group
Wymagania
Nagłówek: ppl.h
Przestrzeń nazw: współbieżność
Anuluj
Podejmuje najlepszą próbę anulowania podzadrzewa pracy zakorzenionej w tej grupie zadań. Każde zadanie zaplanowane w grupie zadań zostanie anulowane przechodnio, jeśli jest to możliwe.
void cancel();
Uwagi
Aby uzyskać więcej informacji, zobacz Anulowanie.
is_canceling
Informuje obiekt wywołujący, czy grupa zadań znajduje się obecnie w trakcie anulowania. Niekoniecznie oznacza to, że cancel
metoda została wywołana w structured_task_group
obiekcie (chociaż z pewnością kwalifikuje tę metodę do zwrócenia true
). Może się zdarzyć, że structured_task_group
obiekt jest wykonywany w tekście, a grupa zadań dalej w drzewie roboczym została anulowana. W takich przypadkach, w których środowisko uruchomieniowe może określić przed upływem czasu, że anulowanie będzie przepływać przez ten structured_task_group
obiekt, true
zostanie również zwrócone.
bool is_canceling();
Wartość zwracana
Wskazanie, czy structured_task_group
obiekt znajduje się w trakcie anulowania (lub jest gwarantowany wkrótce).
Uwagi
Aby uzyskać więcej informacji, zobacz Anulowanie.
uruchom
Planuje zadanie w structured_task_group
obiekcie . Obiekt wywołujący zarządza okresem istnienia task_handle
obiektu przekazanego w parametrze _Task_handle
. Wersja, która przyjmuje parametr _Placement
powoduje, że zadanie jest stronnicze w kierunku wykonywania w lokalizacji określonej przez ten parametr.
template<class _Function>
void run(
task_handle<_Function>& _Task_handle);
template<class _Function>
void run(
task_handle<_Function>& _Task_handle,
location& _Placement);
Parametry
_Funkcja
Typ obiektu funkcji, który zostanie wywołany w celu wykonania treści dojścia zadania.
_Task_handle
Dojście do zaplanowanej pracy. Należy pamiętać, że obiekt wywołujący ponosi odpowiedzialność za okres istnienia tego obiektu. Środowisko uruchomieniowe będzie nadal oczekiwać, że będzie działać do momentu wait
wywołania metody lub run_and_wait
dla tego structured_task_group
obiektu.
_Umieszczenie
Odwołanie do lokalizacji, w której zadanie reprezentowane przez _Task_handle
parametr powinien zostać wykonany.
Uwagi
Środowisko uruchomieniowe tworzy kopię funkcji pracy przekazanej do tej metody. Wszelkie zmiany stanu, które występują w obiekcie funkcji przekazywanym do tej metody, nie będą wyświetlane w kopii tego obiektu funkcji.
structured_task_group
Jeśli destrukcja w wyniku odwijania stosu z wyjątku, nie musisz zagwarantować, że wywołanie zostało wykonane do wait
metody lub run_and_wait
. W takim przypadku destruktor odpowiednio anuluje i czeka na ukończenie zadania reprezentowanego _Task_handle
przez parametr .
Zgłasza wyjątek invalid_multiple_scheduling , jeśli uchwyt zadania podany przez _Task_handle
parametr został już zaplanowany na obiekt grupy zadań za pośrednictwem run
metody i nie było pośredniczące wywołanie metody wait
lub run_and_wait
w tej grupie zadań.
run_and_wait
Planuje uruchomienie zadania wbudowanego w kontekście wywołującym z pomocą obiektu w celu zapewnienia pełnej structured_task_group
obsługi anulowania. task_handle
Jeśli obiekt jest przekazywany jako parametr do run_and_wait
obiektu , obiekt wywołujący jest odpowiedzialny za zarządzanie okresem istnienia task_handle
obiektu. Następnie funkcja czeka, aż wszystkie prace nad structured_task_group
obiektem zostaną ukończone lub anulowane.
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);
Parametry
_Funkcja
Typ obiektu funkcji, który zostanie wywołany w celu wykonania zadania.
_Task_handle
Dojście do zadania, które zostanie uruchomione w tekście w kontekście wywołującym. Należy pamiętać, że obiekt wywołujący ponosi odpowiedzialność za okres istnienia tego obiektu. Środowisko uruchomieniowe będzie nadal oczekiwać, że będzie działać, dopóki run_and_wait
metoda nie zakończy wykonywania.
_Func
Funkcja, która zostanie wywołana w celu wywołania treści pracy. Może to być lambda lub inny obiekt, który obsługuje wersję operatora wywołania funkcji z podpisem void operator()()
.
Wartość zwracana
Wskazanie, czy oczekiwanie zostało spełnione, czy grupa zadań została anulowana z powodu jawnej operacji anulowania lub wyjątku zgłaszanego z jednego z jego zadań. Aby uzyskać więcej informacji, zobacz task_group_status
Uwagi
Należy pamiętać, że co najmniej jedno zadanie zaplanowane do tego structured_task_group
obiektu może być wykonywane w tekście w kontekście wywołującym.
Jeśli co najmniej jedno zadanie zaplanowane do tego structured_task_group
obiektu zgłasza wyjątek, środowisko uruchomieniowe wybierze jeden taki wyjątek od wybranego obiektu i rozpropaguje go z wywołania run_and_wait
metody .
Po powrocie tej funkcji obiekt jest traktowany structured_task_group
w stanie końcowym i nie powinien być używany. Należy pamiętać, że użycie po zwracaniu run_and_wait
metody spowoduje niezdefiniowane zachowanie.
W nietypowej ścieżce wykonywania masz mandat do wywołania tej metody lub wait
metody przed destruktorem structured_task_group
wykonań.
structured_task_group
Tworzy nowy structured_task_group
obiekt.
structured_task_group();
structured_task_group(cancellation_token _CancellationToken);
Parametry
_CancellationToken
Token anulowania do skojarzenia z tą ustrukturyzowaną grupą zadań. Ustrukturyzowana grupa zadań zostanie anulowana po anulowaniu tokenu.
Uwagi
Konstruktor, który przyjmuje token anulowania, tworzy structured_task_group
obiekt, który zostanie anulowany po anulowaniu źródła skojarzonego z tokenem. Udostępnienie jawnego tokenu anulowania izoluje również tę ustrukturyzowaną grupę zadań od udziału w niejawnym anulowaniu z grupy nadrzędnej z innym tokenem lub bez tokenu.
~structured_task_group
structured_task_group
Niszczy obiekt. Oczekuje się, że wywołasz metodę wait
lub run_and_wait
na obiekcie przed wykonaniem destruktora, chyba że destruktor wykonuje w wyniku odwijania stosu z powodu wyjątku.
~structured_task_group();
Uwagi
Jeśli destruktor jest uruchamiany w wyniku normalnego wykonywania (na przykład nie odwijania stosu z powodu wyjątku) ani nie wait
run_and_wait
wywołano metod, destruktor może zgłosić wyjątek missing_wait .
wait
Czeka, aż wszystkie prace nad ukończeniem structured_task_group
lub zostaną anulowane.
task_group_status wait();
Wartość zwracana
Wskazanie, czy oczekiwanie zostało spełnione, czy grupa zadań została anulowana z powodu jawnej operacji anulowania lub wyjątku zgłaszanego z jednego z jego zadań. Aby uzyskać więcej informacji, zobacz task_group_status
Uwagi
Należy pamiętać, że co najmniej jedno zadanie zaplanowane do tego structured_task_group
obiektu może być wykonywane w tekście w kontekście wywołującym.
Jeśli co najmniej jedno zadanie zaplanowane do tego structured_task_group
obiektu zgłasza wyjątek, środowisko uruchomieniowe wybierze jeden taki wyjątek od wybranego obiektu i rozpropaguje go z wywołania wait
metody .
Po powrocie tej funkcji obiekt jest traktowany structured_task_group
w stanie końcowym i nie powinien być używany. Należy pamiętać, że użycie po zwracaniu wait
metody spowoduje niezdefiniowane zachowanie.
W nietypowej ścieżce wykonywania masz mandat do wywołania tej metody lub run_and_wait
metody przed destruktorem structured_task_group
wykonań.
Zobacz też
Przestrzeń nazw współbieżności
task_group, klasa
task_handle, klasa