Sous-routine LAPI_Util

Objectif

Sert de fonction d'encapsuleur pour les opérations de collecte / dispersion de données telles que l'enregistrement et la réservation, pour la mise à jour des informations de port UDP et pour l'obtention de pointeurs vers les fonctions de verrouillage et de signalisation associées à un verrou LAPI partagé.

Bibliothèque

Bibliothèque de disponibilité (liblapi_r.a)

Syntaxe C

#include <lapi.h>
 
int LAPI_Util(hndl, util_cmd)
lapi_handle_t hndl;
lapi_util_t *util_cmd;

Syntaxe FORTRAN

include 'lapif.h'
 
LAPI_UTIL(hndl, util_cmd, ierror)
INTEGER hndl
TYPE (LAPI_UTIL_T) :: util_cmd
INTEGER ierror

Descriptif

Type of call: Programme DGSP (Data gather / scatter program), informations de port UDP et utilitaires de partage de verrous

typedef union {
    lapi_util_type_t    Util_type;  
    lapi_reg_dgsp_t     RegDgsp;    
    lapi_dref_dgsp_t    DrefDgsp;   
    lapi_resv_dgsp_t    ResvDgsp;   
    lapi_reg_ddm_t      DdmFunc;    
    lapi_add_udp_port_t Udp;        
    lapi_pack_dgsp_t    PackDgsp;   
    lapi_unpack_dgsp_t  UnpackDgsp;
    lapi_thread_func_t  ThreadFunc;
} lapi_util_t;

LAPI_REGISTER_DGSP

Vous pouvez utiliser cette opération pour enregistrer un DGSP LAPI que vous avez créé. Pour enregistrer un DGSP LAPI, lapi_dgsp_descr_t idgsp doit être transmis. LAPI renvoie un descripteur (lapi_dg_handle_t dgsp_handle) à utiliser pour tous les futurs appels LAPI. Le dgsp_handle renvoyé par une opération d'enregistrement est identifié comme un type lapi_dg_handle_t , qui est le type approprié pour les appels LAPI_Xfer et LAPI_Util qui prennent un DGSP. dgsp_handle est également défini comme pouvant être transtypé en un pointeur vers un lapi_dgsp_descr_t pour les situations où l'utilisateur LAPI a besoin d'un accès en lecture seule aux informations contenues dans le DGSP en cache. L'opération d'enregistrement fournit un DGSP à LAPI pour une utilisation ultérieure dans les opérations d'envoi, de réception, de conditionnement et de décompression de messages. LAPI crée sa propre copie du DGSP et la protège par le nombre de références. Toutes les opérations LAPI internes qui dépendent d'un DGSP mis en cache dans LAPI garantissent la conservation du DGSP en incrémentant le nombre de références lorsqu'elles commencent une dépendance sur le DGSP et en décrémentant le nombre à la fin de cette dépendance. Une fois enregistré, un DGSP peut être utilisé à partir de n'importe quelle instance LAPI. LAPI_Term ne rejette pas les DGSP.

Vous pouvez enregistrer un DGSP, démarrer une ou plusieurs opérations LAPI à l'aide du DGSP, puis annuler la réservation sans vous soucier du moment où les opérations LAPI qui dépendent du DGSP seront effectuées à l'aide de ce dernier. Pour plus d'informations, voir LAPI_RESERVE_DGSP et LAPI_UNRESERVE_DGSP .

En général, le DGSP que vous créez et transmettez à l'appel LAPI_REGISTER_DGSP à l'aide du paramètre dgsp est supprimé une fois que LAPI a créé et mis en cache sa propre copie. Etant donné que la création de DGSP est complexe, des erreurs utilisateur peuvent se produire, mais une vérification étendue des erreurs lors du transfert de données risque de nuire aux performances. Lors du développement de code qui crée des DGSP, vous pouvez appeler une validation supplémentaire au point d'enregistrement en définissant la variable d'environnement LAPI_VERIFY_DGSP . LAPI_Util renvoie toutes les erreurs détectées. Les erreurs qui existent et qui ne sont pas détectées lors de l'enregistrement provoqueront des problèmes lors du transfert de données. Les erreurs détectées lors du transfert de données seront signalées par un gestionnaire d'erreurs asynchrone. Une erreur de segmentation est un symptôme courant d'un DGSP défaillant. Si plusieurs DGSP sont utilisés, le gestionnaire d'erreurs asynchrones ne pourra pas identifier le DGSP à l'origine de l'erreur. Pour plus d'informations sur le traitement des erreurs asynchrones, voir LAPI_Init.

LAPI_RESERVE_DGSP

Vous pouvez utiliser cette opération pour réserver un DGSP. Cette opération est fournie car un client LAPI peut mettre en cache un descripteur LAPI DGSP pour une utilisation ultérieure. Le client doit s'assurer que le DGSP ne sera pas supprimé avant l'utilisation du descripteur mis en cache. Un descripteur DGSP, qui est défini comme un pointeur vers une description DGSP déjà mise en cache dans LAPI, est transmis à cette opération. Le descripteur DGSP est également défini comme un pointeur de structure, de sorte que les programmes client puissent accéder directement aux informations du DGSP. A moins que le client ne soit certain que le DGSP ne sera pas "non réservé" par une autre unité d'exécution lors de son accès, le client doit placer la fenêtre d'accès entre crochets avec sa propre opération de réservation / annulation de réservation. Le client ne doit pas modifier le DGSP en cache, mais LAPI n'a aucun moyen de l'appliquer. L'opération de réservation incrémente le nombre de références utilisateur, protégeant ainsi le DGSP jusqu'à ce qu'une opération de non-réservation ait lieu. Cela est nécessaire car l'unité d'exécution qui a placé la réservation s'attend à pouvoir utiliser ou examiner le DGSP mis en cache jusqu'à ce qu'elle effectue un appel de non-réservation (qui décrémente le nombre de références utilisateur), même si l'opération de non-réservation qui correspond à l'opération de registre d'origine se produit dans cette fenêtre sur une autre unité d'exécution.

LAPI_UNRESERVE_DGSP

Vous pouvez utiliser cette opération pour désenregistrer ou annuler la réservation d'un DGSP. Cette opération décrémente le nombre de références utilisateur. Si le nombre de références externes et internes est égal à zéro, cette opération permet à LAPI de libérer le DGSP. Toutes les opérations qui décrément un nombre de références font que LAPI vérifie si les deux nombres sont devenus 0 et si tel est le cas, élimine le DGSP. Plusieurs activités LAPI internes incrémentent et décrément un second comptage de référence. Le DGSP mis en cache n'est disponible que lorsque toutes les activités (internes et externes) qui en dépendent et qui utilisent le comptage des références pour le conserver ont déchargé leur référence. Le descripteur DGSP est transmis à LAPI en tant que paramètre de valeur et LAPI n'annule pas le descripteur de l'appelant. Il est de votre responsabilité de ne pas utiliser à nouveau ce descripteur car, lors d'une opération de déréservation, vous avez indiqué que vous ne comptez plus sur le descripteur restant valide.

LAPI_REG_DDM_FUNC

Vous pouvez utiliser cette opération pour enregistrer les fonctions du gestionnaire de distribution des données (DDM). Il fonctionne en conjonction avec l'instruction de la DGSM CONTROL. Il est principalement utilisé pour MPI_Accumulate, mais les clients LAPI peuvent fournir n'importe quelle fonction DDM. Il est également utilisé pour établir une fonction de rappel pour le traitement des données qui sont dispersées dans une mémoire tampon utilisateur côté destination.

typedef long ddm_func_t (        /* return number of bytes processed */
        void      *in,           /* pointer to inbound data          */
        void      *inout,        /* pointer to destination space     */
        long      bytes,         /* number of bytes inbound          */
        int       operand,       /* CONTROL operand value            */
        int       operation      /* CONTROL operation value          */
);

Une fonction DDM intervient entre l'arrivée des données de message et la mémoire tampon cible. L'utilisation la plus courante consiste à combiner des données entrantes avec des données qui se trouvent déjà dans la mémoire tampon cible. Par exemple, si la mémoire tampon cible est un tableau d'entiers et que le message entrant se compose d'entiers, la fonction DDM peut être écrite pour ajouter chaque entier entrant à la valeur qui se trouve déjà dans la mémoire tampon. Les zones opérande et opération de la fonction DDM permettent à une fonction DDM de prendre en charge une série d'opérations avec l'instruction CONTROL en fournissant les valeurs appropriées pour ces zones.

Pour plus d'informations sur la programmation DGSP, voir RSCT for AIX 5L: LAPI Programming Guide .

LAPI_DG_PACK

Vous pouvez utiliser cette opération pour collecter des données dans une mémoire tampon de pack à partir d'une mémoire tampon utilisateur sous le contrôle d'un DGSP. Une mémoire tampon unique peut être condensée par une série d'appels. L'appelant fournit une valeur position qui est initialisée sur le décalage de début dans la mémoire tampon. Chaque opération de conditionnement ajuste position, de sorte que l'opération de conditionnement suivante puisse commencer là où l'opération de conditionnement précédente s'est terminée. En général, une série d'opérations de pack commence par position initialisée sur 0, mais tout décalage est valide. Il n'y a pas d'état transporté d'une opération de conditionnement à l'autre. Chaque opération de conditionnement démarre au début du DGSP qu'elle est transmise.

LAPI_DG_UNPACK

Vous pouvez utiliser cette opération pour disperser des données d'une mémoire tampon condensée vers une mémoire tampon utilisateur sous le contrôle d'un DGSP. Une seule mémoire tampon peut être décompressée par une série d'appels. L'appelant fournit une valeur position qui est initialisée sur le décalage de début dans la mémoire tampon condensée. Chaque opération de déballage ajuste position, de sorte que l'opération de déballage suivante puisse commencer là où s'est terminée l'opération de déballage précédente. En règle générale, une série d'opérations de décompression commence par l'initialisation de position sur 0, mais tout décalage est valide. Aucun état n'est passé d'une opération de déballage à l'autre. Chaque opération de décompression démarre au début du DGSP qu'elle est transmise.

LAPI_ADD_UDP_DEST_PORT

Vous pouvez utiliser cette opération pour mettre à jour les informations de port UDP relatives à la tâche de destination. Cette opération peut être utilisée lorsque vous avez écrit votre propre gestionnaire UDP (udp_h???) et que vous devez prendre en charge la reprise des tâches ayant échoué. Vous ne pouvez pas utiliser cette opération dans l'environnement d'exécution POE.

LAPI_GET_THREAD_FUNC

Vous pouvez utiliser cette opération pour extraire diverses fonctions de verrouillage et de signalisation partagées . L'extraction de ces fonctions est valide uniquement après l'initialisation de LAPI et avant l'arrêt de LAPI. Vous ne devez appeler aucune de ces fonctions après l'arrêt de LAPI.

LAPI utilise la bibliothèque pthread pour la gestion des ID d'unité d'exécution. Vous pouvez donc utiliser pthread_self() pour obtenir l'ID d'unité d'exécution en cours d'exécution et lapi_mutex_getowner_t pour obtenir l'ID d'unité d'exécution qui possède le verrou partagé. Ensuite, vous pouvez utiliser pthread_equal() pour voir si les deux sont identiques.

Fonctions d'unité d'exécution de processus mutex

LAPI_GET_THREAD_FUNC inclut les fonctions d'unité d'exécution de mutex suivantes: verrou de mutex, déverrouillage de mutex, verrou d'essai de mutex et propriétaire d'obtention de mutex.

int (*lapi_mutex_lock_t)(lapi_handle_t hndl);

int (*lapi_mutex_unlock_t)(lapi_handle_t hndl);

int (*lapi_mutex_trylock_t)(lapi_handle_t hndl);

int (*lapi_mutex_getowner_t)(lapi_handle_t hndl, pthread_t *tid);

Fonctions de condition

LAPI_GET_THREAD_FUNC inclut les fonctions condition suivantes: condition attente, condition attente temporisée, condition signal, condition d'initialisation et condition de destruction.

int (*lapi_cond_wait_t)(lapi_handle_t hndl, lapi_cond_t *cond);

int (*lapi_cond_timedwait_t)(lapi_handle_t hndl, 
                             lapi_cond_t *cond, 
                             struct timespec *timeout);

int (*lapi_cond_wait_t)(lapi_handle_t hndl, lapi_cond_t *cond);
typedef int (*lapi_cond_signal_t)(lapi_handle_t hndl, lapi_cond_t *cond);

int (*lapi_cond_init_t)(lapi_handle_t hndl, lapi_cond_t *cond);

int (*lapi_cond_destroy_t)(lapi_handle_t hndl, lapi_cond_t *cond);

Paramètres

ENTREE

hndl

Indique le descripteur LAPI.

Entrée-sortie

cmd util_cmd

Indique le type de commande de la fonction d'utilitaire.

Sortie

erreur ierror

Indique un code retour FORTRAN. Il s'agit toujours du dernier paramètre.

Valeurs renvoyées

SUCCÈS_LAPIEU

Indique que l'appel de fonction a abouti.

ERREUR_LAPI_DGSP

Indique que le DGSP transmis est NULL (en C) ou LAPI_ADDR_NULL (en FORTRAN) ou n'est pas un DGSP enregistré.

ATOME_ERREUR_LAPI_ERR_DGSP_ATOM

Indique que le DGSP a une atom_size inférieure à 0 ou supérieure à MAX_ATOM_SIZE.

BRANCH_ERR_LAPI_ERR_DGSP_BRANCHE

Indique que le DGSP a tenté une branche qui se trouve en dehors du tableau de codes. Cette valeur est renvoyée uniquement en mode de validation.

LAPI_ERR_DG_COPY_SZ

Est renvoyé avec la validation DGSP activée lorsque le bloc MCOPY < 0 ou l'instruction COPY avec les octets < 0. Cette valeur est renvoyée uniquement en mode de validation.

LAPI_ERR_DG_LIBRE

Indique que LAPI a tenté de libérer un DGSP qui n'est pas valide ou qui n'est plus enregistré. Il doit y avoir une opération LAPI_UNRESERVE_DGSP pour fermer l'opération LAPI_REGISTER_DGSP et une opération LAPI_UNRESERVE_DGSP pour chaque opération LAPI_RESERVE_DGSP .

LAPI_ERR_DG_OPC

Indique que le DGSP opcode n'est pas valide. Cette valeur est renvoyée uniquement en mode de validation.

CHEMIN_ERREUR_LAPI_DGSP_STACK

Indique que la profondeur GOSUB du DGSP est supérieure à celle prise en charge par la pile allouée. L'allocation de pile est spécifiée par le membre dgsp->depth. Cette valeur est renvoyée uniquement en mode de validation.

LAPI_ERR_HNDL_INVALID

Indique que le hndl transmis n'est pas valide (non initialisé ou à l'état arrêté).

LAPI_ERR_MEMORY_ÉPUISÉE

Indique que LAPI ne peut pas obtenir de mémoire du système.

LAPI_ERR_UDP_PORT_INFO

Indique que le pointeur d'information udp_port est NULL (en C) ou que la valeur de udp_port est LAPI_ADDR_NULL (en FORTRAN).

ERREUR_UTIL_LAPI_CMD

Indique que le type de commande n'est pas valide.

Exemples C

Emplacement

/usr/lib/liblapi_r.a

Informations connexes

Sous-routines: LAPI_Init, LAPI_Xfer