Documentation du service : Task-Master

Documentation du service : Task-Master
Auteur: SOFTINNOV / Nenad Rakocevic
Date : 11/03/2005
Version: 1.0
Commentaires: [email protected]
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

1. Objet

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).

2. Installation

Le service Task-Master n�cessite que les fichiers suivants soient pr�sent pour fonctionner :
services/
    task-master.r
    task-master/
     task-handler.r
Ces fichiers font partie de l'archive Uniserve . En principe, vous n'avez donc rien de particulier � installer pour utiliser ce service.

3. Description

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][
        ...
    ]
]

4. D�tail de l'API du Task-master

Cette partie d�crit les propri�t�s, les �v�nements et les m�thodes que le service Task-Master fournit � vos services.

4.1. Propri�t�(s)

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).

4.2. Ev�nements

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.

4.3. M�thodes

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 :
do-task: func [data][shared/do-task data self]
ou, si on a besoin de sauvegarder les donn�es (data) du client :
do-task: func [data /local cu][
    cu: client/user-data
    shared/do-task/save data self context [
        queue: cu/queue
        request: cu/request
    ]
]

5. Param�tres du service Task-Master

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.

6. API du Module

6.1. D�finition du Module

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 :
install-module [
    name: 'module-name
    ...
    on-task-received: func [data][
        ...
        response: ...
    ]
]
(NB : vous n'avez pas besoin de pr�charger de script particulier avec 'do ou 'load pour utiliser cette fonction)

6.2. Propri�t�s

Nom Valeur Obligatoire? Description
response any-type! oui donn�es � renvoyer au service appelant.

6.3. Ev�nements

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)..

6.4. Echange de donn�es

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.