CountedCompleter Classe

Définition

[Android.Runtime.Register("java/util/concurrent/CountedCompleter", ApiSince=24, DoNotGenerateAcw=true)]
[Java.Interop.JavaTypeParameters(new System.String[] { "T" })]
public abstract class CountedCompleter : Java.Util.Concurrent.ForkJoinTask

[<Android.Runtime.Register("java/util/concurrent/CountedCompleter", ApiSince=24, DoNotGenerateAcw=true)>]
[<Java.Interop.JavaTypeParameters(new System.String[] { "T" })>]
type CountedCompleter = class
    inherit ForkJoinTask

Héritage

Object

Object

ForkJoinTask

CountedCompleter

Attributs

RegisterAttribute JavaTypeParametersAttribute

Remarques

Avec ForkJoinTask une action de saisie semi-automatique effectuée lorsqu’elle est déclenchée et qu’il n’y a pas d’actions en attente restantes. Les countedCompleters sont en général plus robustes en présence d’étalons de sous-tâches et de blocage que d’autres formes de ForkJoinTasks, mais sont moins intuitifs pour programmer. Les utilisations de CountedCompleter sont similaires à celles d’autres composants basés sur l’achèvement (par exemple java.nio.channels.CompletionHandler), sauf que plusieurs <achèvements em>en attente</em> peuvent être nécessaires pour déclencher l’action #onCompletion(CountedCompleter)d’achèvement, pas seulement une. À moins d’initialiser autrement, le nombre d'#getPendingCount en attente commence à zéro, mais peut être (atomiquement) modifié à l’aide de méthodes #setPendingCount, #addToPendingCountet #compareAndSetPendingCount. Lors de l’appel de , si le nombre d’actions en attente n’est pas différent de zéro, il est décrémenté ; sinon, l’action d’achèvement #tryCompleteest effectuée, et si ce completer lui-même a un completer, le processus est poursuivi avec son completer. Comme c’est le cas avec des composants de synchronisation connexes tels que Phaser et Semaphore, ces méthodes affectent uniquement les nombres internes ; elles n’établissent aucune autre comptabilité interne. En particulier, les identités des tâches en attente ne sont pas conservées. Comme illustré ci-dessous, vous pouvez créer des sous-classes qui enregistrent certaines ou toutes les tâches en attente ou leurs résultats si nécessaire. Comme illustré ci-dessous, les méthodes utilitaires prenant en charge la personnalisation des traversées d’achèvement sont également fournies. Toutefois, étant donné que les CountedCompleters fournissent uniquement des mécanismes de synchronisation de base, il peut être utile de créer d’autres sous-classes abstraites qui conservent des liaisons, des champs et des méthodes de prise en charge supplémentaires appropriées pour un ensemble d’utilisations connexes.

Une classe CountedCompleter concrète doit définir la méthode #compute, qui doit dans la plupart des cas (comme illustré ci-dessous), appeler tryComplete() une fois avant de retourner. La classe peut également remplacer éventuellement la méthode #onCompletion(CountedCompleter) pour effectuer une action à l’achèvement normal et la méthode #onExceptionalCompletion(Throwable, CountedCompleter) pour effectuer une action à toute exception.

Lescompleters comptés ne portent généralement pas de résultats, auquel cas ils sont normalement déclarés comme CountedCompleter<Void>, et retournent null toujours en tant que valeur de résultat. Dans d’autres cas, vous devez remplacer la méthode #getRawResult pour fournir un résultat à partir des join(), invoke()méthodes associées. En règle générale, cette méthode doit retourner la valeur d’un champ (ou d’une fonction d’un ou plusieurs champs) de l’objet CountedCompleter qui contient le résultat à la fin. La méthode #setRawResult par défaut ne joue aucun rôle dans CountedCompleters. Il est possible, mais rarement applicable, de remplacer cette méthode pour conserver d’autres objets ou champs contenant des données de résultat.

Un CountedCompleter qui n’a pas lui-même un completer (c’est-à-dire un pour lequel #getCompleter retourne null) peut être utilisé comme forkJoinTask standard avec cette fonctionnalité ajoutée. Toutefois, tout completer qui à son tour a un autre completer sert uniquement d’assistance interne pour d’autres calculs, de sorte que son propre état de tâche (tel que signalé dans des méthodes telles que ForkJoinTask#isDone) est arbitraire ; cet état change uniquement en cas d’appel explicite de , ForkJoinTask#cancelForkJoinTask#completeExceptionally(Throwable) ou lors de #completel’achèvement exceptionnel de la méthode compute. À l’issue d’une exécution exceptionnelle, l’exception peut être relayée à l’completer d’une tâche (et à son completer, et ainsi de suite), si elle existe et qu’elle n’est pas déjà terminée. De même, l’annulation d’un countedCompleter interne n’a qu’un effet local sur ce completer, ce qui n’est pas souvent utile.

<b>Exemples d’utilisations.</b>

<b>Décomposition récursive parallèle.</b> CountedCompleters peut être organisé dans des arbres similaires à ceux souvent utilisés avec RecursiveActions, bien que les constructions impliquées dans leur configuration varient généralement. Ici, l’completer de chaque tâche est son parent dans l’arborescence de calcul. Même s’ils impliquent un peu plus de comptabilité, CountedCompleters peut être de meilleurs choix lors de l’application d’une opération éventuellement fastidieuse (qui ne peut pas être subdividée) à chaque élément d’un tableau ou d’une collection ; en particulier lorsque l’opération prend beaucoup de temps pour se terminer pour certains éléments que d’autres, soit en raison d’une variation intrinsèque (par exemple, d’E/S) ou d’effets auxiliaires tels que le garbage collection. Étant donné que LesCompleters fournissent leurs propres continuations, d’autres tâches n’ont pas besoin de bloquer l’attente pour les effectuer.

Par exemple, voici une version initiale d’une méthode utilitaire qui utilise la décomposition récursive de division par deux pour diviser le travail en morceaux uniques (tâches feuilles). Même lorsque le travail est fractionné en appels individuels, les techniques basées sur les arborescences sont généralement préférables à l’exécution directe des tâches feuilles, car elles réduisent la communication entre threads et améliorent l’équilibrage de charge. Dans le cas récursif, la seconde de chaque paire de tâches subordonnées pour terminer l’achèvement de leur parent (car aucune combinaison de résultats n’est effectuée, l’implémentation sans opération par défaut de la méthode onCompletion n’est pas substituée). La méthode utilitaire configure la tâche racine et l’appelle (ici, implicitement à l’aide de l’objet ForkJoinPool#commonPool()). Il est simple et fiable (mais pas optimal) de toujours définir le nombre en attente sur le nombre de tâches enfants et d’appeler tryComplete() immédiatement avant de retourner.

{@code
            public static <E> void forEach(E[] array, Consumer<E> action) {
              class Task extends CountedCompleter<Void> {
                final int lo, hi;
                Task(Task parent, int lo, int hi) {
                  super(parent); this.lo = lo; this.hi = hi;
                }

                public void compute() {
                  if (hi - lo >= 2) {
                    int mid = (lo + hi) >>> 1;
                    // must set pending count before fork
                    setPendingCount(2);
                    new Task(this, mid, hi).fork(); // right child
                    new Task(this, lo, mid).fork(); // left child
                  }
                  else if (hi > lo)
                    action.accept(array[lo]);
                  tryComplete();
                }
              }
              new Task(null, 0, array.length).invoke();
            }}

Cette conception peut être améliorée en notant que dans le cas récursif, la tâche n’a rien à faire après la saisie de sa tâche appropriée, afin de pouvoir appeler directement sa tâche de gauche avant de retourner. (Il s’agit d’un analogue de la suppression de la récursivité de la queue.) En outre, lorsque la dernière action d’une tâche consiste à fork ou à appeler un sous-tâche (un « appel de queue »), l’appel à tryComplete() optimiser peut être optimisé, au coût de l’affichage du nombre en attente « off by one ».

{@code
                public void compute() {
                  if (hi - lo >= 2) {
                    int mid = (lo + hi) >>> 1;
                    setPendingCount(1); // looks off by one, but correct!
                    new Task(this, mid, hi).fork(); // right child
                    new Task(this, lo, mid).compute(); // direct invoke
                  } else {
                    if (hi > lo)
                      action.accept(array[lo]);
                    tryComplete();
                  }
                }}

En guise d’optimisation supplémentaire, notez que la tâche de gauche n’a même pas besoin d’exister. Au lieu de créer un nouveau, nous pouvons continuer à utiliser la tâche d’origine et ajouter un nombre en attente pour chaque fourche. En outre, étant donné qu’aucune tâche dans cette arborescence implémente une #onCompletion(CountedCompleter) méthode, tryComplete peut être remplacée par #propagateCompletion.

{@code
                public void compute() {
                  int n = hi - lo;
                  for (; n >= 2; n /= 2) {
                    addToPendingCount(1);
                    new Task(this, lo + n/2, lo + n).fork();
                  }
                  if (n > 0)
                    action.accept(array[lo]);
                  propagateCompletion();
                }}

Lorsque les nombres en attente peuvent être précomputés, ils peuvent être établis dans le constructeur :

{@code
            public static <E> void forEach(E[] array, Consumer<E> action) {
              class Task extends CountedCompleter<Void> {
                final int lo, hi;
                Task(Task parent, int lo, int hi) {
                  super(parent, 31 - Integer.numberOfLeadingZeros(hi - lo));
                  this.lo = lo; this.hi = hi;
                }

                public void compute() {
                  for (int n = hi - lo; n >= 2; n /= 2)
                    new Task(this, lo + n/2, lo + n).fork();
                  action.accept(array[lo]);
                  propagateCompletion();
                }
              }
              if (array.length > 0)
                new Task(null, 0, array.length).invoke();
            }}

D’autres optimisations de ces classes peuvent impliquer des classes spécialisées pour les étapes feuilles, la sous-division par exemple, quatre, au lieu de deux par itération, et l’utilisation d’un seuil adaptatif au lieu de toujours subdivider vers des éléments uniques.

<b>Recherche.</b> Une arborescence de CountedCompleters peut rechercher une valeur ou une propriété dans différentes parties d’une structure de données et signaler un résultat java.util.concurrent.atomic.AtomicReference AtomicReference dès qu’un objet est trouvé. Les autres peuvent interroger le résultat pour éviter tout travail inutile. (Vous pouvez également #cancel annuler d’autres tâches, mais il est généralement plus simple et plus efficace de les laisser remarquer que le résultat est défini et, si tel est le cas, ignorez le traitement supplémentaire.) Illustration à nouveau d’un tableau utilisant le partitionnement complet (encore une fois, dans la pratique, les tâches feuilles traiteront presque toujours plusieurs éléments) :

{@code
            class Searcher<E> extends CountedCompleter<E> {
              final E[] array; final AtomicReference<E> result; final int lo, hi;
              Searcher(CountedCompleter<?> p, E[] array, AtomicReference<E> result, int lo, int hi) {
                super(p);
                this.array = array; this.result = result; this.lo = lo; this.hi = hi;
              }
              public E getRawResult() { return result.get(); }
              public void compute() { // similar to ForEach version 3
                int l = lo, h = hi;
                while (result.get() == null && h >= l) {
                  if (h - l >= 2) {
                    int mid = (l + h) >>> 1;
                    addToPendingCount(1);
                    new Searcher(this, array, result, mid, h).fork();
                    h = mid;
                  }
                  else {
                    E x = array[l];
                    if (matches(x) && result.compareAndSet(null, x))
                      quietlyCompleteRoot(); // root task is now joinable
                    break;
                  }
                }
                tryComplete(); // normally complete whether or not found
              }
              boolean matches(E e) { ... } // return true if found

              public static <E> E search(E[] array) {
                  return new Searcher<E>(null, array, new AtomicReference<E>(), 0, array.length).invoke();
              }
            }}

Dans cet exemple, ainsi que d’autres dans lesquels les tâches n’ont pas d’autres effets, à l’exception compareAndSet d’un résultat commun, l’appel sans condition de fin de tryComplete la tâche peut être rendu conditionnel (if (result.get() == null) tryComplete();) car aucune autre comptabilité n’est nécessaire pour gérer les achèvements une fois la tâche racine terminée.

<b>Sous-tâches d’enregistrement.</b> Les tâches CountedCompleter qui combinent les résultats de plusieurs tâches subordonnées doivent généralement accéder à ces résultats dans la méthode #onCompletion(CountedCompleter). Comme illustré dans la classe suivante (qui effectue une forme simplifiée de map-reduce où les mappages et les réductions sont tous de type E), une façon de le faire dans les conceptions de division et de conquête est d’avoir chaque sous-tâche enregistrer son frère, afin qu’il soit accessible dans la méthode onCompletion. Cette technique s’applique aux réductions dans lesquelles l’ordre de combinaison des résultats gauche et droit n’a pas d’importance ; les réductions ordonnées nécessitent des désignations explicites de gauche/droite. Les variantes d’autres rationalisations observées dans les exemples ci-dessus peuvent également s’appliquer.

{@code
            class MyMapper<E> { E apply(E v) {  ...  } }
            class MyReducer<E> { E apply(E x, E y) {  ...  } }
            class MapReducer<E> extends CountedCompleter<E> {
              final E[] array; final MyMapper<E> mapper;
              final MyReducer<E> reducer; final int lo, hi;
              MapReducer<E> sibling;
              E result;
              MapReducer(CountedCompleter<?> p, E[] array, MyMapper<E> mapper,
                         MyReducer<E> reducer, int lo, int hi) {
                super(p);
                this.array = array; this.mapper = mapper;
                this.reducer = reducer; this.lo = lo; this.hi = hi;
              }
              public void compute() {
                if (hi - lo >= 2) {
                  int mid = (lo + hi) >>> 1;
                  MapReducer<E> left = new MapReducer(this, array, mapper, reducer, lo, mid);
                  MapReducer<E> right = new MapReducer(this, array, mapper, reducer, mid, hi);
                  left.sibling = right;
                  right.sibling = left;
                  setPendingCount(1); // only right is pending
                  right.fork();
                  left.compute();     // directly execute left
                }
                else {
                  if (hi > lo)
                      result = mapper.apply(array[lo]);
                  tryComplete();
                }
              }
              public void onCompletion(CountedCompleter<?> caller) {
                if (caller != this) {
                  MapReducer<E> child = (MapReducer<E>)caller;
                  MapReducer<E> sib = child.sibling;
                  if (sib == null || sib.result == null)
                    result = child.result;
                  else
                    result = reducer.apply(child.result, sib.result);
                }
              }
              public E getRawResult() { return result; }

              public static <E> E mapReduce(E[] array, MyMapper<E> mapper, MyReducer<E> reducer) {
                return new MapReducer<E>(null, array, mapper, reducer,
                                         0, array.length).invoke();
              }
            }}

Ici, la méthode onCompletion prend une forme commune à de nombreuses conceptions d’achèvement qui combinent les résultats. Cette méthode de style de rappel est déclenchée une fois par tâche, dans l’un des deux contextes différents dans lesquels le nombre en attente est, ou devient, zéro : (1) par une tâche elle-même, si son nombre en attente est égal à zéro lors de l’appel de , ou (2) par l’une de tryCompleteses sous-tâches lorsqu’ils se terminent et décrémentent le nombre en attente à zéro. L’argument caller distingue les cas. Le plus souvent, lorsque l’appelant est this, aucune action n’est nécessaire. Sinon, l’argument de l’appelant peut être utilisé (généralement via un cast) pour fournir une valeur (et/ou des liens vers d’autres valeurs) à combiner. En supposant l’utilisation appropriée des nombres en attente, les actions à l’intérieur onCompletion se produisent (une fois) à l’achèvement d’une tâche et de ses sous-tâches. Aucune synchronisation supplémentaire n’est requise dans cette méthode pour garantir la sécurité des threads des accès aux champs de cette tâche ou à d’autres tâches terminées.

<b>Traversées d’achèvement.</b> Si l’utilisation onCompletion pour traiter les achèvements est inapplicable ou peu pratique, vous pouvez utiliser des méthodes #firstComplete et #nextComplete créer des traversées personnalisées. Par exemple, pour définir un MapReducer qui fractionne uniquement les tâches de droite sous la forme du troisième exemple ForEach, les achèvements doivent réduire de manière coopérative le long des liens de sous-tâches nonhaussés, ce qui peut être effectué comme suit :

{@code
            class MapReducer<E> extends CountedCompleter<E> { // version 2
              final E[] array; final MyMapper<E> mapper;
              final MyReducer<E> reducer; final int lo, hi;
              MapReducer<E> forks, next; // record subtask forks in list
              E result;
              MapReducer(CountedCompleter<?> p, E[] array, MyMapper<E> mapper,
                         MyReducer<E> reducer, int lo, int hi, MapReducer<E> next) {
                super(p);
                this.array = array; this.mapper = mapper;
                this.reducer = reducer; this.lo = lo; this.hi = hi;
                this.next = next;
              }
              public void compute() {
                int l = lo, h = hi;
                while (h - l >= 2) {
                  int mid = (l + h) >>> 1;
                  addToPendingCount(1);
                  (forks = new MapReducer(this, array, mapper, reducer, mid, h, forks)).fork();
                  h = mid;
                }
                if (h > l)
                  result = mapper.apply(array[l]);
                // process completions by reducing along and advancing subtask links
                for (CountedCompleter<?> c = firstComplete(); c != null; c = c.nextComplete()) {
                  for (MapReducer t = (MapReducer)c, s = t.forks; s != null; s = t.forks = s.next)
                    t.result = reducer.apply(t.result, s.result);
                }
              }
              public E getRawResult() { return result; }

              public static <E> E mapReduce(E[] array, MyMapper<E> mapper, MyReducer<E> reducer) {
                return new MapReducer<E>(null, array, mapper, reducer,
                                         0, array.length, null).invoke();
              }
            }}

<b>Déclencheurs.</b> Certains CountedCompleters ne sont jamais forked, mais servent plutôt de bits de plomberie dans d’autres conceptions ; y compris ceux dans lesquels l’achèvement d’une ou plusieurs tâches asynchrones déclenche une autre tâche asynchrone. Par exemple :

{@code
            class HeaderBuilder extends CountedCompleter<...> { ... }
            class BodyBuilder extends CountedCompleter<...> { ... }
            class PacketSender extends CountedCompleter<...> {
              PacketSender(...) { super(null, 1); ... } // trigger on second completion
              public void compute() { } // never called
              public void onCompletion(CountedCompleter<?> caller) { sendPacket(); }
            }
            // sample use:
            PacketSender p = new PacketSender();
            new HeaderBuilder(p, ...).fork();
            new BodyBuilder(p, ...).fork();}

Ajouté dans la version 1.8.

Documentation Java pour java.util.concurrent.CountedCompleter.

Les parties de cette page sont des modifications basées sur le travail créé et partagé par le projet Android Open Source et utilisés en fonction des termes décrits dans la licence d’attribution Creative Commons 2.5.

Constructeurs

Propriétés

Méthodes

Implémentations d’interfaces explicites

Méthodes d’extension

S’applique à