Documentation du service : Task-Master Auteur: SOFTINNOV / Nenad Rakocevic Date : 11/03/2005 Version: 1.0 Commentaires: info@softinnov.com Traduction : Philippe Le Goff
Table of Contents
1. Objet
2. Installation
3. Description
4. Détail de l'API du Task-master
4.1. Propriété(s)
4.2. Evénements
4.3. Méthodes
5. Paramètres du service Task-Master
6. API du Module
6.1. Définition du Module
6.2. Propriétés
6.3. Evénements
6.4. Echange de données
Uniserve est bâti sur le principe du multiplexage de ports de communication au sein d'un processus unique. C'est une façon très efficace de gérer des évènements réseau, mais il y a une contre-partie : c'est mono-processus. Cela signifie que vous ne devez pas écrire du "code bloquant" (comme lire un gros fichier sur un disque, attendre des saisies des utilisateurs, etc...). Pour les cas où vous avez besoin d'effectuer des traitements bloquants pour votre application tout en laissant Uniserve traiter les évènements réseau, vous devrez lancer un nouveau processus REBOL pour traiter votre code bloquant, et utiliser un mécanisme de type IPC (Inter-Process Communication) pour faire communiquer vos processus.Le service Task-Master vous fournit le framework pour gérer en tâche de fond des processus qui doivent être exécutés à part. Ce service fournit les fonctionnalités suivantes :
- Gestion de processus externes (lancement, suppression).
- Communication entre processus (via des communications TCP asynchrones).
- Intégration propre et simplifiée avec vos services (au travers d'évènements dédiés).
Le service Task-Master nécessite que les fichiers suivants soient présent pour fonctionner :
Ces fichiers font partie de l'archive Uniserve . En principe, vous n'avez donc rien de particulier à installer pour utiliser ce service.services/ task-master.r task-master/ task-handler.r
Le service Task-Master fonctionne selon le modèle "pre-forking" (lancement préalable de processus). Lorsque le service est démarré, il génére un certain nombre (paramétrable) de processus REBOL en tâches de fond. Une fois lancés, ces processus se connectent automatiquement au processus principal d'Uniserve, via le protocole TCP du service Task-Master et sont enregistrés par le service comme étant disponible.Lorsque vous demandez au service Task-Master d'exécuter une action en tâche de fond, le service examine la liste interne des processus, prend le premier processus non occupé, et lui transfère vos données avec quelques informations contextuelles en plus.
Lorsque l'action est terminée, le processus renvoie les données au service Task-Master qui expédie les résultats au service émetteur en appelant les évenements appropriées définis dans celui-ci.
S'il n'y a pas de processus libres lorsqu'une action est demandée, un nouveau processus est démarré (sauf si la limite supérieure du nombre de processus est atteinte).
Si le nombre maximum de processus est atteint, la requête est placée dans une file d'attente et assignée à un processus dès que possible.
Si le processus principal d'Uniserve se termine, tous les processus en tâches de fond se terminent automatiquement.
Voici un exemple typique d'utilisation du Task-Master dans un service UniServe :
install-service [ ... module: 'module-name ... on-received: ...[ ... shared/do-task some-data 'self ... ] ... on-task-done: func [data][ ... ] ... on-task-failed: func [reason][ ... ] ]
Cette partie décrit les propriétés, les événements et les méthodes que le service Task-Master fournit à vos services.
Cette propriété doit être indiquée dans la définition de votre service. Elle peut être modifiée dynamiquement n'importe où dans le source de votre service.
Nom Valeur Obligatoire? Description module word! oui Le nom par défaut du module pour le traitement en tâche de fond. Ce nom doit être exactement le même que celui du fichier contenant le code source du module (exemple CGI pour le fichier CGI.r) sans l'extension ".r" (attention aux systèmes d'exploitation sensibles à la casse).
Vous devez implémenter les évènements suivants afin que votre service puisse traiter les résultats du travail effectué en tâche de fond.
Nom Prototype Description on-task-done func [data [binary!]] Est appelé quand le processus a retourné une réponse.
data : la réponse émise par le module (données formattées suivant le module).. data is nettoyé une fois la fonction évaluée, de sorte qu'il faut utilisez 'copy si les données doivent être conservées.on-task-failed func [reason] Est appelée si le traitement a échoué.
reason : une valeur indiquant la cause de l'échec. Cette valeur est habituellement un mot (word!) mais peut être n'importe quelle valeur renvoyée par le module.
Codes d'erreurs Le service Task-Master peut retourner les codes d'erreurs suivants (l'argument 'reason de 'on-task-failed) :
'error : une erreur de communication s'est produite dans le processus en tâche de fond.
'overload : surcharge du serveur. Tous les processsus sont occupés, le nombre maximum de processus est atteint, et la file d'attente est pleine.
Au chargement, le service Task-Master place la fonction do-task dans l'espace partagé d'Uniserve, la rendant accessible à tous les services.
Nom Prototype Description shared/do-task [data service /save locals] Lance une nouvelle tache. Cette fonction n'est pas bloquante, de sorte que son usage est sans risque dans les fonctions évènementielles.
data : données à envoyer au module.
service : référence à votre service (habituellement, 'self suffit).
/save : option permettant de sauvegarder le contexte local (client).
locals : contexte client (client/user-data).
Raccourcis pratiques Il est pratique de créer un raccourci pour shared/do-task dans ses services. On peux utiliser le code suivant :
ou, si on a besoin de sauvegarder les données (data) du client :do-task: func [data][shared/do-task data self]
do-task: func [data /local cu][ cu: client/user-data shared/do-task/save data self context [ queue: cu/queue request: cu/request ] ]
Vous pouvez modifier quelques uns des paramétres de démarrage du service Task-Master. Dans la version actuelle, ces modifications sont à apporter directement dans le code source du service Task-Master.
Nom Valeur Obligatoire? Description pool-start integer! oui Nombre de processus au démarrage du service Task-Master (par défaut: 2) pool-max integer! oui Nombre maximum de processus (par défaut: 4). job-max integer! oui Taille maximum de la file d'attente des requêtes à éxécuter (par défaut: 100). Les requêtes sont mises en file d'attente lorsque aucun processus n'est disponible pour les executer et que le nombre maximum de processus est atteint.
Un module est un script REBOL qui implémente l'API fournie par le task-handler. Ce module sera exécuté en tâche de fond, contrôlé par le service Task-Master d'Uniserve.Pour ajouter un nouveau module, le nom de fichier le décrivant doit correspondre au nom du module (à l'exception de l'extension ".r"). Ce fichier doit être placé dans le dossier %modules de l'arborescence d'Uniserve.
Chaque module est déclaré en utilisant la fonction install-module. Un en-tête (header) REBOL est requis (même si son contenu est vide). Voici le squelette type d'un module :
(NB : vous n'avez pas besoin de précharger de script particulier avec 'do ou 'load pour utiliser cette fonction)install-module [ name: 'module-name ... on-task-received: func [data][ ... response: ... ] ]
Nom Valeur Obligatoire? Description response any-type! oui données à renvoyer au service appelant.
Nom Prototype Description on-task-received func [data [string!]] est appelé lorsqu'un processus recoit une nouvelle tâche à exécuter.
data : donnée envoyée par le service appelant, en format "moldé" (peut être n'importe quelle type de valeur REBOL)..
Vous pouvez échanger n'importe quelle sorte de données entre le service appelant et le module en tâche de fond. Le format d'échange est libre et à votre convenance. Le service Task-Master va sérialiser (format mold) les données passées à la fonction shared/do-task avant de les envoyer au processus en tâche de fond. En retour, le Task-Master renverra la réponse au service appelant, sous une forme binaire et moldée (via l'événement 'on-task-done). Donc utiliser la séquence : load to-string pour recharger les données dans leur format natif.Essayez de garder les données échangées aussi petites que possibles pour garantir les meilleurs performances.