CountedCompleter Classe

Definizione

[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

Ereditarietà

Object

Object

ForkJoinTask

CountedCompleter

Attributi

RegisterAttribute JavaTypeParametersAttribute

Commenti

Oggetto ForkJoinTask con un'azione di completamento eseguita quando viene attivato e non sono presenti azioni in sospeso rimanenti. CountedCompleters è in generale più affidabile in presenza di stalli secondari e blocchi rispetto ad altre forme di ForkJoinTasks, ma sono meno intuitivi per programmare. Gli usi di CountedCompleter sono simili a quelli di altri componenti basati sul completamento (ad esempio java.nio.channels.CompletionHandler), ad eccezione del fatto che potrebbero essere necessari più <completamenti em>in sospeso</em> per attivare l'azione #onCompletion(CountedCompleter)di completamento, non solo uno. A meno che non venga inizializzato diversamente, il conteggio #getPendingCount in sospeso inizia a zero, ma può essere modificato (in modo atomico) usando i metodi #setPendingCount, #addToPendingCounte #compareAndSetPendingCount. Dopo la chiamata di , se il conteggio delle #tryCompleteazioni in sospeso è diverso da zero, viene decrementato; in caso contrario, viene eseguita l'azione di completamento e, se il completamento stesso dispone di un completore, il processo viene continuato con il relativo completore. Come avviene con i componenti di sincronizzazione correlati, Phaser ad esempio e Semaphore, questi metodi influiscono solo sui conteggi interni; non stabiliscono ulteriori contabilità interna. In particolare, le identità delle attività in sospeso non vengono mantenute. Come illustrato di seguito, è possibile creare sottoclassi che registrano alcune o tutte le attività in sospeso o i relativi risultati quando necessario. Come illustrato di seguito, vengono forniti anche metodi di utilità che supportano la personalizzazione degli attraversamenti di completamento. Tuttavia, poiché CountedCompleters fornisce solo meccanismi di sincronizzazione di base, può essere utile creare altre sottoclassi astratte che mantengono collegamenti, campi e metodi di supporto aggiuntivi appropriati per un set di utilizzi correlati.

Una classe CountedCompleter concreta deve definire il metodo #compute, che deve essere nella maggior parte dei casi (come illustrato di seguito), richiamare tryComplete() una volta prima di restituire . La classe può anche eseguire facoltativamente l'override del metodo #onCompletion(CountedCompleter) per eseguire un'azione al completamento normale e il metodo #onExceptionalCompletion(Throwable, CountedCompleter) per eseguire un'azione in caso di eccezione.

CountedCompleters spesso non genera risultati, nel qual caso vengono normalmente dichiarati come CountedCompleter<Void>e restituirà null sempre come valore di risultato. In altri casi, è necessario eseguire l'override del metodo #getRawResult per fornire un risultato da join(), invoke()e i metodi correlati. In generale, questo metodo deve restituire il valore di un campo (o una funzione di uno o più campi) dell'oggetto CountedCompleter che contiene il risultato al completamento. Il metodo #setRawResult per impostazione predefinita non svolge alcun ruolo in CountedCompleters. È possibile, ma raramente applicabile, eseguire l'override di questo metodo per gestire altri oggetti o campi che contengono i dati dei risultati.

Un CountedCompleter che non dispone di un completore (ad esempio, uno per il quale #getCompleter restituisce null) può essere usato come normale ForkJoinTask con questa funzionalità aggiunta. Tuttavia, qualsiasi completere che a sua volta dispone di un altro completer funge solo da helper interno per altri calcoli, quindi il proprio stato dell'attività (come indicato nei metodi come ForkJoinTask#isDone) è arbitrario. Questo stato cambia solo in caso di chiamate esplicite di #complete, ForkJoinTask#cancelForkJoinTask#completeExceptionally(Throwable) o al completamento eccezionale del metodo compute. In caso di completamento eccezionale, l'eccezione può essere inoltrata al completore di un'attività (e al relativo completore e così via), se ne esiste uno e non è già stato completato. Analogamente, l'annullamento di un countedCompleter interno ha solo un effetto locale su tale completere, quindi non è spesso utile.

<b>Esempi di utilizzo.</b>

<b>Scomposizione ricorsiva parallela.</b> CountedCompleters può essere disposto in alberi simili a quelli usati con RecursiveActions, anche se le costruzioni coinvolte nella configurazione variano in genere. In questo caso, il completore di ogni attività è il relativo elemento padre nell'albero di calcolo. Anche se comportano un po ' più di contabilità, CountedCompleters può essere scelte migliori quando si applica un'operazione potenzialmente dispendiosa in termini di tempo (che non può essere ulteriormente suddivisa) a ogni elemento di una matrice o di una raccolta; in particolare quando l'operazione richiede una quantità significativa di tempo per il completamento di alcuni elementi rispetto ad altri, sia a causa di variazioni intrinseche (ad esempio I/O) o effetti ausiliari come Garbage Collection. Poiché CountedCompleters fornisce le proprie continuazioni, le altre attività non devono bloccare l'attesa di eseguirle.

Ad esempio, ecco una versione iniziale di un metodo di utilità che usa la scomposizione ricorsiva di divisione per due per dividere il lavoro in singole parti (attività foglia). Anche quando il lavoro è suddiviso in singole chiamate, le tecniche basate su albero sono in genere preferibili alla creazione diretta di fork delle attività foglia, perché riducono la comunicazione tra thread e migliorano il bilanciamento del carico. Nel caso ricorsivo, il secondo di ogni coppia di sottoattività per completare il completamento dei trigger padre (poiché non viene eseguita alcuna combinazione di risultati, l'implementazione no-op predefinita del metodo onCompletion non viene sottoposta a override). Il metodo di utilità configura l'attività radice e lo richiama (in questo caso, usando in modo implicito ).ForkJoinPool#commonPool() È semplice e affidabile (ma non ottimale) impostare sempre il conteggio in sospeso sul numero di attività figlio e chiamare tryComplete() immediatamente prima della restituzione.

{@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();
            }}

Questa progettazione può essere migliorata notando che nel caso ricorsivo, l'attività non ha nulla da fare dopo la creazione di fork dell'attività destra, in modo da poter richiamare direttamente l'attività a sinistra prima di restituire. Si tratta di un analogo alla rimozione della ricorsione della coda. Inoltre, quando l'ultima azione in un'attività consiste nel creare un fork o richiamare una sottoattività (una "chiamata finale"), la chiamata a tryComplete() può essere ottimizzata, a costo di rendere il conteggio in sospeso "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();
                  }
                }}

Come ulteriore ottimizzazione, si noti che l'attività a sinistra non deve esistere neanche. Anziché crearne uno nuovo, è possibile continuare a usare l'attività originale e aggiungere un conteggio in sospeso per ogni fork. Inoltre, poiché nessuna attività in questo albero implementa un #onCompletion(CountedCompleter) metodo, tryComplete può essere sostituita con #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();
                }}

Quando i conteggi in sospeso possono essere precompilate, possono essere stabiliti nel costruttore:

{@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();
            }}

Le ottimizzazioni aggiuntive di tali classi possono comportare la specializzazione delle classi per i passaggi foglia, dividendo per esempio quattro, anziché due per iterazione e usando una soglia adattiva invece di suddividere sempre i singoli elementi.

<b>Ricerca.</b> Un albero di CountedCompleters può cercare un valore o una proprietà in parti diverse di una struttura di dati e segnalare un risultato java.util.concurrent.atomic.AtomicReference AtomicReference non appena ne viene trovato uno. Gli altri possono eseguire il polling del risultato per evitare operazioni non necessarie. È anche possibile #cancel annullare altre attività, ma in genere è più semplice ed efficiente solo consentire loro di notare che il risultato è impostato e, in tal caso, ignorare altre elaborazioni. Illustrando di nuovo con una matrice usando il partizionamento completo (ancora una volta, in pratica, le attività foglia elaboreranno quasi sempre più di un elemento):

{@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();
              }
            }}

In questo esempio, così come altri in cui le attività non hanno altri effetti ad eccezione di compareAndSet un risultato comune, la chiamata incondizionato finale di tryComplete potrebbe essere resa condizionale (if (result.get() == null) tryComplete();) perché non è necessaria alcuna ulteriore contabilità per gestire i completamenti al termine dell'attività radice.

<b>Sottoattività di registrazione.</b> Le attività CountedCompleter che combinano i risultati di più sottoattività devono in genere accedere a questi risultati nel metodo #onCompletion(CountedCompleter). Come illustrato nella classe seguente (che esegue una forma semplificata di map-reduce in cui i mapping e le riduzioni sono tutti di tipo E), un modo per eseguire questa operazione in progetti di divisione e conquista è avere ogni sottoattività registrare il relativo elemento di pari livello, in modo che sia accessibile nel metodo onCompletion. Questa tecnica si applica alle riduzioni in cui l'ordine di combinazione dei risultati sinistro e destro non è importante; le riduzioni ordinate richiedono designazioni esplicite a sinistra/destra. Possono essere applicate anche varianti di altri streamlining illustrati negli esempi precedenti.

{@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();
              }
            }}

In questo caso, il metodo onCompletion assume una forma comune a molte progettazioni di completamento che combinano i risultati. Questo metodo di tipo callback viene attivato una volta per ogni attività, in uno dei due diversi contesti in cui il conteggio in sospeso è o diventa zero: (1) da un'attività stessa, se il conteggio in sospeso è zero al momento della chiamata di tryCompleteo (2) da una delle relative sottoattività quando completano e decrementano il conteggio in sospeso su zero. L'argomento caller distingue i case. Nella maggior parte dei casi, quando il chiamante è this, non è necessaria alcuna azione. In caso contrario, l'argomento del chiamante può essere usato (in genere tramite cast) per fornire un valore (e/o collegamenti ad altri valori) da combinare. Supponendo l'uso corretto dei conteggi in sospeso, le azioni all'interno onCompletion si verificano (una volta) al completamento di un'attività e delle relative sottoattività. Non è necessaria alcuna sincronizzazione aggiuntiva all'interno di questo metodo per garantire la thread safety degli accessi ai campi di questa attività o ad altre attività completate.

<b>Attraversamenti di completamento.</b> Se si usa onCompletion per elaborare i completamenti è inapplicabile o scomodo, è possibile usare metodi #firstComplete e #nextComplete per creare attraversamenti personalizzati. Ad esempio, per definire un MapReducer che suddivide solo le attività di destra sotto forma del terzo esempio ForEach, i completamenti devono ridurre in modo cooperativo i collegamenti secondari non esauriti, che possono essere eseguiti come segue:

{@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>Trigger.</b> Alcuni CountedCompleters non sono mai forked, ma servono invece come bit di idraulica in altre progettazioni, incluse quelle in cui il completamento di una o più attività asincrone attiva un'altra attività asincrona. Ad esempio:

{@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();}

Aggiunta nella versione 1.8.

Documentazione java per java.util.concurrent.CountedCompleter.

Le parti di questa pagina sono modifiche basate sul lavoro creato e condiviso dal progetto Open Source Android e usato in base ai termini descritti nella licenza Creative Commons 2.5 Attribuzione.

Costruttori

Proprietà

Metodi

Implementazioni dell'interfaccia esplicita

Metodi di estensione

Si applica a