libshmem/doc/man3/libshmem.3

'\" t
.\" @(#)LIBSM.3 99/10/27 SMA;
.TH LIBSM 3 "27 Oct 1999"
.SH NOM
LIBSM (librairie de memoires partagees)
.SH SYNOPSIS
.LP
.BI "cc [flag ...] file ... -lver -ldl -lnode -lshmem [library ...]"
.LP
.BI "#include <shmem.h>"
.LP
.BI "SMT_Status SM_Library_Open ( int " Instance ", const char * " Context_Name ", SMT_Flags " Open_Mode " );"
.LP
.BI "SMT_Status SM_Library_Instance_Get ( int * " Instance " );"
.LP
.BI "SMT_Status SM_Library_Context_Set ( char * " Context_Name " );"
.LP
.BI "SMT_Status SM_Library_Context_Get ( char ** " Context_Name " );"
.LP
.BI "SMT_Status SM_Library_Close ( SMT_Flags " Close_Mode " );"
.LP
.BI "SMT_Status SM_Library_Stderr_Set ( FILE * " Out " );"
.LP
.BI "SMT_Status SM_Heap_Exist ( char * " Heap_Name " );"
.LP
.BI "SMT_Status SM_Heap_Open ( char * " Heap_Name ", SMT_Heap ** " Heap ", size_t " Seg_Size " , SMT_Flags " Open_Flags ", int * " Locked " );"
.LP
.BI "SMT_Status SM_Heap_Close ( SMT_Heap * " Heap " );"
.LP
.BI "SMT_Status SM_Heap_End ( char * " Heap_Name " );"
.LP
.BI "SMT_Status SM_Heap_Compress ( SMT_Heap * " Heap ", size_t * " Size " );"
.LP
.BI "SMT_Status SM_Heap_Check ( SMT_Heap * " Heap ", int * " Nb_Detected " , int * " Nb_Corrected ", FILE * " Out " );"
.LP
.BI "SMT_Status SM_Heap_Lock ( SMT_Heap * " Heap ", SMT_Flags " Lock_Flags ", int * " Locked " );"
.LP
.BI "SMT_Status SM_Heap_Unlock ( SMT_Heap * " Heap " );"
.LP
.BI "SMT_Status SM_Heap_Config ( SMT_Heap * " Heap ", SMT_Tag " Tag ", ... );"
.LP
.BI "SMT_Status SM_Chunk_Alloc ( SMT_Heap * " Heap ", void ** " Ptr ", size_t " Size " );"
.LP
.BI "SMT_Status SM_Chunk_Free ( SMT_Heap * " Heap ", void * " Ptr " );"
.LP
.SH GENERALITES
.LP
La librairie LIBSM permet de gerer des espaces de memoire partagee.
Ces espaces de memoire partagee (notion de 'heap') sont references dans une base geree par la librairie.
.LP
La librairie permet de gerer plusieurs instances, chacune ayant une base qui lui est propre.
Pour chaque instance, des contextes d'utilisation pourront etre definis.
.LP
Les heaps sont constitues de blocs memoire (notion de 'chunk') qui pourront etre alloues et desalloues par les programmes y accedant de maniere concurrente.
.LP
Chaque heap presente la particularite d'etre :
.LP
.RS 3
- identifie par un nom unique dans la base
.LP
- securise : les acces concurrents sont geres par l'utilisation de semaphores
.RS -3
.LP
La librairie propose des fonctions de gestion :
.LP
.RS 3
- de la base de la librairie (initialisation, ouverture, fermeture, destruction).
.LP
- des heaps (creation, ouverture, verrouillage, compression, deverrouillage, fermeture, destruction)
.LP
- des chunks (allocation, desallocation)
.RS -3
.LP
.BI "BASE DE HEAPS"
.LP
La base constitue l'espace commun a tous les utilisateurs d'une instance de la librairie.
.LP
Cette base est initialisee une premiere fois et reference la liste de tous les heaps de l'instance.
.LP
Cette base est protegee par un systeme de verrou permettant de gerer les acces concurrents aux differents heaps. 
.LP
.I NB
: la base contient un heap 'systeme' qui gere les ressources des autres heaps (dits heaps 'utilisateur').
Ce heap 'systeme' est un heap prive qui ne devra pas etre accede directement par les utilisateurs de la librairie.
.LP
.BI "NOTION DE HEAP"
.LP
Un heap est un espace de memoire partagee reference dans la base.
Il y est identifie de maniere unique par son nom.
.LP
La notion de contexte d'utilisation permet de distinguer des heaps en prefixant leur nom par ce contexte.
.LP
Les acces concurrents aux ressources d'un heap sont geres par un systeme de verrou qui autorise :
.LP
.RS 3
- plusieurs acces en lecture simultanes (verrous partages)
.LP
- un seul acces en ecriture (verrou exclusif)
.RS -3
.LP
.I NB
: un verrouillage est opere en mode 'wait', ce qui signifie que les processus desirant verrouiller une ressource non disponible sera mis en attente jusqu'a sa mise en disponibilite.
.LP
.BI "NOTION DE CHUNK"
.LP
Un chunk est un bloc d'allocation memoire au sein d'un heap.
.LP
Un chunk appartient necessairement a une liste de chunks alloues au sein du heap (ACR) ou bien a celle de ses chunks libres (FCR).
.LP
.SH TYPES
.LP
La librairie met a la disposition des utilisateurs les types suivants :
.LP
.BI "SMT_Flags
.LP
.RS 3
Ce type d'indicateur permet de preciser le mode d'ouverture d'une instance/d'un heap de la librairie.
.LP
.RS 3
- 
.B SMD_OPEN
: pour ouvrir une instance/un heap existante/existant
.LP
- 
.B SMD_CREAT
: pour creer l'instance/le heap si elle/il n'existe pas
.LP
.RS -3
.LP
Pour l'ouverture de la librairie, il permet en outre de preciser le mode de debugging :
.LP 
.RS 3
- 
.B SM_DEBUG_NONE
: aucun message d'erreur n'est affiche
.LP
- 
.B SM_DEBUG
: les messages d'erreur generes par la librairie LIBSHMEM sont affiches sur la sortie standard d'erreur
.LP
- 
.B SM_DEBUG_ALL
: les messages d'erreur generes par toutes les librairies sous-jacentes a la LIBSHMEM sont affiches sur la sortie standard d'erreur
.RS -3
.LP
Pour l'ouverture d'un heap, il permet de preciser son type de verrouillage :
.LP
.RS 3
- 
.B SMD_WRITE
: acces en ecriture (pose d'un verrou exclusif )
.LP
- 
.B SMD_READ
: acces en lecture (pose d'un verrou partage)
.LP
- 
.B SMD_UNDEF
: aucun verrou.
.LP
.RS -3
.RS -3
.LP
.BI "SMT_Heap
.LP
.RS 3
Ce type permet de designer un heap ouvert par le processus courant.
.LP
C'est le seul type concernant les heaps qui sera manipule par les utilisateurs a travers les API de la librairie.
.RS -3
.LP
.SH FONCTIONS
.LP
.BI "SMT_Status SM_Library_Open ( int " Instance ", const char * " Context_Name ", SMT_Flags " Open_Mode " );"
.LP
.RS 3
Cette fonction permet d'acceder aux ressources partagees d'une instance de la librairie (base de heap, heap 'systeme').
Elle devra necessairement etre appelee par tout programme utilisant la librairie.
.LP
Cette fonction attend les parametres suivants :
.LP
.RS 3
* (In)
.I Instance
: num<75>ro de l'instance a ouvrir.
.LP
.I NB
: si cet argument vaut 0, alors c'est la variable d'environnement $INSTANCE qui definira le num<75>ro de l'instance (1000 sinon).
.LP
* (In)
.I Context
: nom du contexte a utiliser.
.LP
.I NB
: si cet argument est NULL, alors c'est la variable d'environnement $CONTEXT qui definira le nom du contexte, ("CTX" sinon).
.LP
* (In)
.I Open_Mode
: le mode d'ouverture de l'instance (
.B SMD_CREATE
pour la creation de l'instance, ou
.B SMD_OPEN
pour une ouverture simple)
.LP
.I NB
: cette valeur pourra etre combinee avec un mode de debugging (
.B SMD_DEBUG_NONE
,
.B SMD_DEBUG
ou
.B SMD_DEBUG_ALL
)
.LP
.RS -3
Outre l'acces aux ressources de l'instance, cette fonction provoque le verrouillage de la base en lecture.
L'utilisateur de la librairie est ainsi assure de l'existence de ces ressources tout au long de leur utilisation.
.LP
.I NB
: le mode d'ouverture
.B SMD_CREATE
est reserve aux administrateurs.
.RS -3
.LP
.BI "SMT_Status SM_Library_Instance_Get ( int * " Instance " );"
.LP
.RS 3
Cette fonction permet de recuperer dans l'argument
.I Instance 
le num<75>ro de l'instance utilisee.
.RS -3
.LP
.BI "SMT_Status SM_Library_Context_Set ( char * " Context_Name " );"
.LP
.RS 3
Cette fonction permet de definir
.I Context_Name
comme etant le nom du nouveau contexte d'utilisation de l'instance de la librairie LIBSHMEM.
.LP
.I NB
: specifier un contexte implique que tous les heaps manipules seront prefixes par le nom de ce contexte.
.RS -3
.LP
.BI "SMT_Status SM_Library_Context_Get ( char ** " Context_Name " );"
.LP
.RS 3
Cette fonction permet de recuperer dans l'argument
.I Context_Name
le nom du contexte utilise.
.RS -3
.LP
.BI "SMT_Status SM_Library_Close ( SMT_Flags " Close_Flags " );"
.LP
.RS 3
Cette fonction permet de fermer l'instance de la librairie LIBSM.
Elle libere egalement le verrou en lecture qui avait ete pose sur la base lors de l'ouverture de l'instance.
Cette fonction doit donc etre systematiquement appelee a la fin de chaque programme utilisant la librairie.
.LP
L'argument
.I Close_Flags
est le mode de fermeture de l'instance :
.LP
.RS 3
- 
.B SMD_CLOSE
pour fermer simplement l'instance
.LP
- 
.B SMD_DESTROY
pour detruire en outre toutes les ressources de l'instance
.LP
.RS -3
.LP
.I NB
: le mode de fermeture 
.B SMD_DESTROY
est reserve aux administrateurs.
.LP
Bien entendu, la destruction des ressouces de l'instance ne sera pas possible tant qu'il existera d'autres processus utilisant la meme instance.
.RS -3
.LP
.BI "SMT_Status SM_Library_Stderr_Set ( FILE * " Out " );"
.LP
.RS 3
Cette fonction permet de definir
.I Out
comme la sortie standard des messages d'erreur generes par la librarie.
.RS -3
.LP
.BI "SMT_Status SM_Heap_Exist ( char * " Heap_Name " );"
.LP
.RS 3
Cette fonction permet de tester si un heap existe deja dans la base.
.LP
L'argument
.I Heap_Name
est le nom du heap a tester.
.LP
.RS -3
.BI "SMT_Status SM_Heap_Open ( char * " Heap_Name ", SMT_Heap ** " Heap ", size_t " Seg_Size ", SMT_Flags " Open_Flags ", int * " Locked " );"
.LP
.RS 3
Cette fonction permet d'ouvrir ou de creer un heap 'utilisateur' dans la base.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Heap_Name
: le nom du heap
.LP
* (Out)
.I Heap
: l'adresse d'un pointeur sur le heap a ouvrir
.LP
* (In)
.I Seg_Size
: la taille des segments qui composeront le heap (une fois le heap cree, cette taille peut etre modifiee via la fonction SM_Heap_Config).
.LP
.I NB
: si cet argument est nul, la taille sera par defaut de 102400 octets. 
.LP
* (In)
.I Open_Flags
: le mode d'acces qui determine d'une part l'ouverture ou la creation du heap et d'autre part son type de verrouillage.
.LP
.I NB
: les deux valeurs
.B SMD_OPEN
et
.B SMD_CREATE
peuvent etre combinees.
.LP
* (In)
.I Locked
: un pointeur sur un indicateur de verrouillage : il indique si le verrou a effectivement ete pose ou si le heap etait deja verrouille dans ce mode
.RS -3
.LP
.I NB
: le heap cree est constitue d'un seul segment de donnees et contient un unique chunk libre correspondant a ce premier segment de donnees.
.LP
.RS -3
.LP
.BI "SMT_Status SM_Heap_Close ( SMT_Heap * " Heap ");"
.LP
.RS 3
Cette fonction permet de fermer un heap ouvert.
.LP
Elle permet non seulement de detacher les ressources du heap du processus appelant, mais elle permet aussi de liberer le verrou pose lors de l'ouverture du heap.
.LP
L'argument
.I Heap
est un pointeur sur un heap ouvert.
.RS -3
.LP
.BI "SMT_Status SM_Heap_End ( char * " Heap_Name " );"
.LP
.RS 3
Cette fonction permet de detruire un heap.
.LP
L'argument
.I Heap_Name
designe le nom du heap a detruire.
.LP
.RS -3
.BI "SMT_Status SM_Heap_Compress ( SMT_Heap * " Heap ", size_t * " Size " );"
.LP
.RS 3
Cette fonction permet de compresser un heap, ce qui consiste a fusionner les chunks libres dont les adresses se suivent.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Heap
: un pointeur sur un heap ouvert
.LP
* (Out)
.I Size
: un pointeur sur la taille gagnee par compression
.RS -3
.RS -3
.LP
.BI "SMT_Status SM_Heap_Check ( SMT_Heap * " Heap ", int * " Nb_Detected " , int * " Nb_Corrected ", FILE * " Out " );"
.LP
.RS 3
Cette fonction permet de corriger les structures qui constituent un heap dans le cas ou celles-ci contiendraient des incoherences.
.LP
Un rapport complet de toutes les erreurs detectees et corrigees sur chacune des structures du heap est affiche.
.LP
Elle doit recevoir les arguments suivants :
.RS 3
.LP
* (In)
.I Heap
: un pointeur sur un heap ouvert
.LP
* (Out)
.I Nb_Detected
: un pointeur sur le nombre d'erreurs detectees
.LP
* (Out)
.I Nb_Corrected
: un pointeur sur le nombre d'erreurs corrigees
.LP
* (In)
.I Out
: un pointeur sur le flux de sortie du rapport
.LP
.RS -3
.I NB
: cette fonction est automatiquement activee lors de l'ouverture d'un heap qui est dans un etat invalide (c.a.d un heap dont une mise a jour n'a pas ete a son terme).
.LP
Si toutes les erreurs detectees n'ont pas pu etre corrigees, le heap est declare corrompu et ne sera plus accessible par personne.
.LP
.RS -3
.BI "SMT_Status SM_Heap_Lock ( SMT_Heap * " Heap ", SMT_Flags " Lock_Flags ", int * " Locked " );"
.LP
.RS 3
Cette fonction permet de poser un verrou sur un heap.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Heap
: un pointeur sur un heap ouvert
.LP
* (In)
.I Lock_Flags
: le mode de verrouillage
.LP
* (Out)
.I Locked
: un pointeur sur un indicateur de verrouillage qui indique si le verrou a effectivement ete pose ou si le heap etait deja verrouille dans ce mode
.LP
.RS -3
.I NB
: si le heap est deja verrouille avec le mode demande, alors l'indicateur de verrouillage sera valorise a FALSE.
.LP
Si le heap est deja verrouille avec un autre type de verrou, alors la fonction retournera
.B SMS_KO
.
.RS -3
.LP
.BI "SMT_Status SM_Heap_Unlock ( SMT_Heap * " Heap " );"
.LP
.RS 3
Cette fonction permet d'oter le verrou qui a ete pose sur un heap.
.LP
L'argument
.I Heap
est un pointeur sur le heap a deverrouiller.
.RS -3
.LP
.BI "SMT_Status SM_Heap_Config ( SMT_Heap * " Heap ", SMT_Tag " Tag ", ... );"
.LP
.RS 3
Cette fonction permet de configurer certain aspects d'un heap.
.LP
Elle doit recevoir les aruments suivants :
.LP
.RS 3
* (In)
.I Heap
: un pointeur sur le heap a configurer.
.LP
* (In)
.I Tag
: le type de configuration
.LP
.RS 3
-
.B SMD_SEGMENT_SIZE
: definition de la taille (en octets) des nouveaux segments de donnees qui composeront le heap (par defaut, les heaps sont composes de segments de 102 400 octets).
.LP
-
.B SMD_HEAP_LIMIT
: limitation de la taille totale des segments de donnees qui composent le heap (par defaut, un heap n'est pas limite en taille).
.LP
-
.B SMD_AUTO_COMPRESS
: nombre de chunks libres a partir duquel le heap est automatiquement compresse (la valeur SMD_NO_AUTO_COMPRESS permet de desactiver cette procedure automatique).
.LP
NB : cette limite est fixee par defaut a 1 000 chunks.
.LP
.RS -3
.RS -3
.RS -3
.BI "SMT_Status SM_Chunk_Alloc ( SMT_Heap * " Heap ", void ** " Ptr ", size_t " Size " );"
.LP
.RS 3
Cette fonction permet de reserver de la memoire dans un heap.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Heap
: un pointeur sur un heap ouvert
.LP
* (In)
.I Size
: la taille du chunk (en octets)
.LP
* (Out)
.I Ptr
: l'adresse du pointeur de chunk
.RS -3
.LP
.RS -3
.BI "SMT_Status SM_Chunk_Free ( SMT_Heap * " Heap ", void * " Ptr " );"
.LP
.RS 3
Cette fonction permet de liberer de la memoire dans un heap.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Heap
: un pointeur sur un heap ouvert
.LP
* (In)
.I Ptr
: un pointeur de chunk
.RS -3
.RS -3
.LP
.SH CODE RETOUR
.LP
Toutes les fonctions constituant l'API de la librairie retourne une valeur de type 
.B SMT_Status
:
.LP
.RS 3
-
.B SMS_OK
: la fonction s'est correctement executee et a produit un resultat
.LP
-
.B SMS_KO
: la fonction s'est correctement executee mais n'a pas produit de resultat
.LP
-
.B SMS_ERRAPI
: la fonction a ete appelee avec des arguments de valeur incorrecte
.LP
-
.B SMS_ERRMEM
: la fonction ne s'est pas correctement executee pour un probleme d'allocation memoire
.LP
-
.B SMS_ERRSHM
: la fonction ne s'est pas correctement executee pour un probleme relatif a la memoire partagee
.LP
-
.B SMS_ERRSIG
: une operation sur semaphore a ete interrompue par un signal
.LP
-
.B SMS_ERRSEM
: la fonction ne s'est pas correctement executee pour un probleme relatif a l'utilisation des semaphores
.LP
.RS -3
.I NB
: la macro
.B SM_ERROR()
permet de tester si un code retour correspond a une erreur.
.LP
En cas d'erreur, la variable
.B SM_Error_Msg
contient un message du type :
.LP
.RS 3
Error <Nom fonction> : <message d'erreur>
.RS -3
.LP
.I NB
: dans la mesure du possible, la librairie tente en cas de probleme de revenir a la situation precedant l'appel a la fonction.
.LP
Toutefois, pour les cas plus difficiles, la librairie propose une procedure de verification et de correction (
.B SM_Heap_Check
) qui permet de corriger des incoherences sur les structures de donnees constituant un heap.
.RS -3
.LP
.SH VOIR AUSSI
.B libnode
(3)