Xcraft activity manager
npm install xcraft-core-activityLe module xcraft-core-activity est un gestionnaire d'activités pour le framework Xcraft qui fonctionne comme un ordonnanceur intelligent. Il gÚre l'exécution des commandes en les plaçant dans des listes d'attente ou d'exécution selon des rÚgles de concurrence spécifiques, permettant de contrÎler finement l'ordre d'exécution et la parallélisation des activités dans l'écosystÚme Xcraft.
- Structure du module
- Fonctionnement global
- Exemples d'utilisation
- Interactions avec d'autres modules
- Détails des sources
Le module est composé de trois fichiers principaux :
- lib/activity.js : Classe principale Activities qui implémente l'ordonnanceur
- lib/index.js : Point d'entrée qui exporte l'instance singleton
- activity.js : Commandes Xcraft exposées sur le bus de communication
Le module expose une instance singleton de la classe Activities qui hérite d'EventEmitter pour gérer les événements internes d'orchestration.
Le gestionnaire d'activités fonctionne selon un systÚme d'ordonnancement événementiel basé sur des rÚgles de concurrence strictes :
Le systÚme utilise un modÚle événementiel interne pour orchestrer le flux d'exécution :
- wait : Déclenché pour évaluer toutes les activités en attente
- run : Déclenché pour démarrer l'exécution d'une activité
- ĂvĂ©nements de fin : finished ou error pour marquer la fin d'une activitĂ©
Une activitĂ© peut ĂȘtre exĂ©cutĂ©e uniquement si toutes ces conditions sont respectĂ©es :
1. UnicitĂ© par ORC : La mĂȘme commande avec le mĂȘme nom d'ORC n'est pas dĂ©jĂ en cours d'exĂ©cution
2. Gestion de la parallélisation :
- L'activité est marquée comme parallÚle (parallel: true), OU
- Seules des activités parallÚles sont actuellement en cours d'exécution
1. Ajout : L'activité est ajoutée à la liste d'attente via execute()
2. Génération d'ID : Un identifiant unique est généré avec FlakeId
3. Ăvaluation : Le systĂšme vĂ©rifie si l'activitĂ© peut ĂȘtre exĂ©cutĂ©e immĂ©diatement
4. Exécution : Si les conditions sont remplies, l'activité passe en liste d'exécution
5. Surveillance : Le systÚme s'abonne aux événements de fin d'activité
6. Finalisation : L'activité se termine et déclenche l'évaluation des activités en attente
Le systÚme distingue deux types d'activités :
- Activités exclusives (parallel: false) : Une seule peut s'exécuter à la fois
- Activités parallÚles (parallel: true) : Peuvent s'exécuter simultanément
``javascript
const activity = require('xcraft-core-activity');
// Exécution d'une commande exclusive
activity.execute(
'database.migrate',
{id: 'msg-123', orcName: 'main-orc'},
(cmd, msg) => {
// Cette commande ne peut pas s'exécuter en parallÚle
console.log(Executing exclusive ${cmd} for ${msg.orcName});`
// Logique de migration de base de données
},
false // Activité exclusive
);
`javascriptParallel execution of ${cmd}
// Exécution d'une commande parallÚle (lecture de données)
activity.execute(
'data.fetch',
{id: 'msg-456', orcName: 'worker-orc'},
(cmd, msg) => {
// Cette commande peut s'exécuter en parallÚle avec d'autres
console.log();`
// Logique de récupération de données
},
true // Activité parallÚle
);
`javascript
// Via le systĂšme de commandes Xcraft
const busClient = require('xcraft-core-busclient').getGlobal();
// Envoyer la commande de statut
busClient.command.send('activity.status', {});
// Ăcouter la rĂ©ponse
busClient.events.subscribe('activity.status', (status) => {
console.log('Activités en cours :', status.running);
console.log('Activités en attente :', status.waiting);
});
`
`javascript
// AccĂšs direct Ă l'instance singleton
const activity = require('xcraft-core-activity');
// Obtenir le statut de toutes les activités
const status = activity.status();
console.log('Ătat actuel :', status);
`
Le module interagit étroitement avec plusieurs composants de l'écosystÚme Xcraft :
- [xcraft-core-busclient] : Utilise le client bus global pour s'abonner aux événements de fin d'activité et gérer le cycle de vie
- [xcraft-core-log] : SystÚme de logging intégré pour tracer l'exécution et le débogage des activités
- [xcraft-core-server] : Le serveur charge automatiquement les commandes exposées par ce module
- flake-idgen : Génération d'identifiants uniques distribués pour chaque activité
- biguint-format : Formatage des identifiants FlakeId en représentation hexadécimale
Classe principale Activities qui implémente le gestionnaire d'activités. Elle maintient l'état complet du systÚme via deux collections principales :
- _waiting : Map des activités en attente d'exécution avec leurs métadonnées
- _running : Map des activités en cours d'exécution
- _flakeIdGen : Générateur d'identifiants uniques pour les activités
#### Méthodes publiques
- execute(cmd, msg, action, parallel) â Ajoute une nouvelle activitĂ© Ă la liste d'attente. L'activitĂ© sera automatiquement exĂ©cutĂ©e dĂšs que les conditions de concurrence le permettent.
- status() â Retourne un objet dĂ©taillĂ© contenant l'Ă©tat actuel de toutes les activitĂ©s, organisĂ© en sections running et waiting.pause(id)
- â MĂ©thode rĂ©servĂ©e pour la mise en pause d'une activitĂ© (non implĂ©mentĂ©e).resume(id)
- â MĂ©thode rĂ©servĂ©e pour la reprise d'une activitĂ© (non implĂ©mentĂ©e).kill(id)
- â MĂ©thode rĂ©servĂ©e pour l'arrĂȘt forcĂ© d'une activitĂ© (non implĂ©mentĂ©e).
#### Méthodes privées
- _canExecute(activity) â Algorithme central qui dĂ©termine si une activitĂ© peut ĂȘtre exĂ©cutĂ©e selon les rĂšgles de concurrence Ă©tablies.
- _run(activity) â Lance l'exĂ©cution effective d'une activitĂ©, gĂšre l'abonnement aux Ă©vĂ©nements de fin et maintient l'Ă©tat du systĂšme.
- _isRunning(activity) â VĂ©rifie si une activitĂ© identique (mĂȘme commande et mĂȘme ORC) est dĂ©jĂ en cours d'exĂ©cution.
- _isParallel(activity) â DĂ©termine si une activitĂ© est marquĂ©e comme parallĂšle.
- _haveOnlyParallels() â VĂ©rifie si toutes les activitĂ©s en cours sont parallĂšles, permettant l'exĂ©cution d'activitĂ©s exclusives.
- _getActivityName(activity) â GĂ©nĂšre un nom unique pour l'activitĂ© au format orcName::command.
Point d'entrée minimaliste qui exporte l'instance singleton de la classe Activities, garantissant un état global cohérent dans toute l'application.
Module d'exposition des commandes Xcraft qui permet l'interaction avec le gestionnaire d'activités via le bus de communication.
#### Commandes disponibles
- status â Commande parallĂšle qui interroge le gestionnaire et publie le statut de toutes les activitĂ©s via l'Ă©vĂ©nement activity.status`. Cette commande peut s'exĂ©cuter en parallĂšle car elle est en lecture seule.
---
_Document mis Ă jour_
[xcraft-core-busclient]: https://github.com/Xcraft-Inc/xcraft-core-busclient
[xcraft-core-log]: https://github.com/Xcraft-Inc/xcraft-core-log
[xcraft-core-server]: https://github.com/Xcraft-Inc/xcraft-core-server