Phaser Classe

Définition

[Android.Runtime.Register("java/util/concurrent/Phaser", DoNotGenerateAcw=true)]
public class Phaser : Java.Lang.Object

[<Android.Runtime.Register("java/util/concurrent/Phaser", DoNotGenerateAcw=true)>]
type Phaser = class
    inherit Object

Héritage

Object

Object

Phaser

Attributs

RegisterAttribute

Remarques

Barrière de synchronisation réutilisable, similaire à la fonctionnalité et CountDownLatch prenant CyclicBarrier en charge une utilisation plus flexible.

<b>Inscription.</b> Contrairement aux autres obstacles, le nombre de parties <inscrites></em> à synchroniser sur un phaser peut varier au fil du temps. Les tâches peuvent être inscrites à tout moment (à l’aide de méthodes #register, #bulkRegisterou de formes de constructeurs établissant des nombres initiaux de parties) et éventuellement désinscrire à tout arrivée (utilisation #arriveAndDeregister). Comme c’est le cas avec la plupart des constructions de synchronisation de base, l’inscription et la désinscription affectent uniquement les nombres internes ; ils n’établissent aucune autre comptabilité interne, de sorte que les tâches ne peuvent pas interroger s’ils sont inscrits. (Toutefois, vous pouvez introduire une telle comptabilité en sous-classe cette classe.)

<b>Synchronisation.</b> Comme un CyclicBarrier, un Phaser peut être attendu à plusieurs reprises. La méthode #arriveAndAwaitAdvance a un effet analogue à java.util.concurrent.CyclicBarrier#await CyclicBarrier.await. Chaque génération d’un phaser a un numéro de phase associé. Le nombre de phases commence à zéro et avance lorsque toutes les parties arrivent au phaser, encapsulant autour de zéro après avoir atteint Integer.MAX_VALUE. L’utilisation de numéros de phase permet un contrôle indépendant des actions à l’arrivée à un phaser et en attendant d’autres, via deux types de méthodes qui peuvent être appelées par n’importe quelle partie inscrite :

<ul>

<li><b>Arrivée.</b> Méthodes #arrive et #arriveAndDeregister enregistrement d’arrivée. Ces méthodes ne bloquent pas, mais retournent un numéro< de phase d’arrivée em>> associé <; autrement dit, le numéro de phase du phaser auquel l’arrivée a été appliquée. Lorsque la partie finale d’une phase donnée arrive, une action facultative est effectuée et la phase avance. Ces actions sont effectuées par la partie qui déclenche une avance de phase et sont organisées en substituant la méthode #onAdvance(int, int), qui contrôle également l’arrêt. La substitution de cette méthode est similaire à, mais plus flexible qu’en fournissant une action de barrière à un CyclicBarrier.

<li><b>En attente.<La méthode #awaitAdvance /b> nécessite un argument indiquant un numéro de phase d’arrivée et retourne lorsque le phaseur avance vers (ou est déjà à) une autre phase. Contrairement aux constructions similaires utilisant CyclicBarrier, la méthode awaitAdvance continue d’attendre même si le thread en attente est interrompu. Les versions d’interruption et de délai d’attente sont également disponibles, mais les exceptions rencontrées lorsque les tâches attendent d’interruption ou avec le délai d’attente ne modifient pas l’état du phaseur. Si nécessaire, vous pouvez effectuer une récupération associée dans les gestionnaires de ces exceptions, souvent après l’appel forceTermination. Les phaseurs peuvent également être utilisés par les tâches qui s’exécutent dans un ForkJoinPool. La progression est assurée si le niveau de parallélisme du pool peut prendre en charge le nombre maximal de parties bloquées simultanément.

</ul>

<b>Arrêt.</b> Un phaser peut entrer un <état em>termination</em> , qui peut être vérifié à l’aide de la méthode #isTerminated. Lors de l’arrêt, toutes les méthodes de synchronisation retournent immédiatement sans attendre l’avance, comme indiqué par une valeur de retour négative. De même, les tentatives d’inscription à l’arrêt n’ont aucun effet. L’arrêt est déclenché lorsqu’un appel de onAdvance retours est déclenché true. L’implémentation par défaut retourne true si une désinscription a provoqué le nombre de parties inscrites à zéro. Comme illustré ci-dessous, lorsque les phases contrôlent des actions avec un nombre fixe d’itérations, il est souvent pratique de remplacer cette méthode pour provoquer l’arrêt lorsque le numéro de phase actuel atteint un seuil. La méthode #forceTermination est également disponible pour libérer brusquement les threads en attente et leur permettre de se terminer.

<b>Hiérarchisation.</b> Les phaseurs peuvent être>< em hiérarchisé</em> (c’est-à-dire construits dans des structures d’arborescence) pour réduire la contention. Les phaseurs avec un grand nombre de parties qui auraient autrement des coûts de contention de synchronisation lourds peuvent être configurés afin que les groupes de sous-phases partagent un parent commun. Cela peut augmenter considérablement le débit même s’il entraîne une surcharge plus élevée par opération.

Dans une arborescence de phases hiérarchisé, l’inscription et la désinscription des phaseurs enfants avec leur parent sont gérées automatiquement. Chaque fois que le nombre de parties inscrites d’un phaseur enfant devient non zéro (tel qu’établi dans le #Phaser(Phaser,int) constructeur, #registerou #bulkRegister), le phaseur enfant est inscrit auprès de son parent. Chaque fois que le nombre de parties inscrites devient zéro en raison d’un appel de #arriveAndDeregister, le phaseur enfant est désinscrit de son parent.

<b>Surveillance.</b> Bien que les méthodes de synchronisation ne soient appelées que par des parties inscrites, l’état actuel d’un phaser peut être surveillé par n’importe quel appelant. À un moment donné, il y a #getRegisteredParties des parties au total, #getArrivedParties dont elles sont arrivées à la phase actuelle (#getPhase). Lorsque les parties restantes#getUnarrivedParties arrivent, la phase avance. Les valeurs retournées par ces méthodes peuvent refléter des états temporaires. Elles ne sont donc pas généralement utiles pour le contrôle de synchronisation. La méthode #toString retourne des instantanés de ces requêtes d’état dans un formulaire pratique pour la surveillance informelle.

Effets de cohérence de la mémoire : actions avant toute forme de méthode <arrive i>happen-before</i> une avance de phase correspondante et les actions onAdvance (le cas échéant), qui à leur tour se produisent avant les actions suivant l’avance de phase.

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

Un Phaser peut être utilisé au lieu d’un CountDownLatch contrôle d’une action d’un coup servant un nombre variable de parties. L’idiome classique concerne la configuration de cette méthode pour commencer par s’inscrire, puis démarrer toutes les actions, puis annuler l’inscription, comme dans :

{@code
            void runTasks(List<Runnable> tasks) {
              Phaser startingGate = new Phaser(1); // "1" to register self
              // create and start threads
              for (Runnable task : tasks) {
                startingGate.register();
                new Thread(() -> {
                  startingGate.arriveAndAwaitAdvance();
                  task.run();
                }).start();
              }

              // deregister self to allow threads to proceed
              startingGate.arriveAndDeregister();
            }}

L’une des façons de faire en sorte qu’un ensemble de threads effectue plusieurs fois des actions pour un nombre donné d’itérations consiste à remplacer onAdvance:

{@code
            void startTasks(List<Runnable> tasks, int iterations) {
              Phaser phaser = new Phaser() {
                protected boolean onAdvance(int phase, int registeredParties) {
                  return phase >= iterations - 1 || registeredParties == 0;
                }
              };
              phaser.register();
              for (Runnable task : tasks) {
                phaser.register();
                new Thread(() -> {
                  do {
                    task.run();
                    phaser.arriveAndAwaitAdvance();
                  } while (!phaser.isTerminated());
                }).start();
              }
              // allow threads to proceed; don't wait for them
              phaser.arriveAndDeregister();
            }}

Si la tâche principale doit attendre ultérieurement l’arrêt, elle peut réinscrire, puis exécuter une boucle similaire :

{@code
              // ...
              phaser.register();
              while (!phaser.isTerminated())
                phaser.arriveAndAwaitAdvance();}

Les constructions associées peuvent être utilisées pour attendre des nombres de phases particuliers dans des contextes où vous êtes sûr que la phase ne sera jamais encapsuler Integer.MAX_VALUE. Par exemple :

{@code
            void awaitPhase(Phaser phaser, int phase) {
              int p = phaser.register(); // assumes caller not already registered
              while (p < phase) {
                if (phaser.isTerminated())
                  // ... deal with unexpected termination
                else
                  p = phaser.arriveAndAwaitAdvance();
              }
              phaser.arriveAndDeregister();
            }}

Pour créer un ensemble de n tâches à l’aide d’une arborescence de phases, vous pouvez utiliser le code du formulaire suivant, en supposant qu’une classe Task avec un constructeur acceptant un Phaser enregistrement auprès de la construction. Après l’appel, build(new Task[n], 0, n, new Phaser())ces tâches peuvent ensuite être démarrées, par exemple en envoyant un pool :

{@code
            void build(Task[] tasks, int lo, int hi, Phaser ph) {
              if (hi - lo > TASKS_PER_PHASER) {
                for (int i = lo; i < hi; i += TASKS_PER_PHASER) {
                  int j = Math.min(i + TASKS_PER_PHASER, hi);
                  build(tasks, i, j, new Phaser(ph));
                }
              } else {
                for (int i = lo; i < hi; ++i)
                  tasks[i] = new Task(ph);
                  // assumes new Task(ph) performs ph.register()
              }
            }}

La meilleure valeur de dépend principalement des taux de TASKS_PER_PHASER synchronisation attendus. Une valeur aussi faible que quatre peut être appropriée pour les organismes de tâches extrêmement petits par phase (donc des taux élevés) ou jusqu’à des centaines pour des instances extrêmement volumineuses.

<b>Notes d’implémentation :</b> Cette implémentation limite le nombre maximal de parties à 65535. Les tentatives d’inscription de parties supplémentaires aboutissent à IllegalStateException. Toutefois, vous pouvez et devez créer des phaseurs hiérarchisé pour prendre en charge des ensembles arbitrairement volumineux de participants.

Ajouté dans la version 1.7.

Documentation Java pour java.util.concurrent.Phaser.

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 à