Rx3/libdatastr
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

Première version

Browse Source
This commit is contained in:
smas 2000-07-28 15:30:55 +00:00
commit dbebe02bdf
8 changed files with 5024 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

539
lib/datastr.h Normal file
View File

@ -0,0 +1,539 @@
#ifndef _LIBDATASTR
#define _LIBDATASTR
#ifdef __cplusplus
extern "C" {
#endif
#include <shmem.h>
/* Code retour des fonctions constituant l'API */
typedef long DST_Status;
#define DSS_OK SMS_OK /* La fonction s'est correctement exécutée et a produit un résultat */
#define DSS_KO SMS_KO /* La fonction s'est correctement exécutée mais n'a pas produit de résultat */
#define DSS_YES SMS_OK /* Résultat booléen positif */
#define DSS_NO SMS_KO /* Résultat booléen négatif */
#define DSS_ERRMEM SMS_ERRMEM /* Problème d'allocation mémoire */
#define DSS_ERRAPI SMS_ERRAPI /* Utilisation incorrecte des API */
#define DSS_ERRSHM SMS_ERRSHM /* Problème relatif aux segments de mémoire partagée */
#define DSS_ERRSEM SMS_ERRSEM /* Problème relatif à l'utilisation des sémaphores */
#define DSS_ERRSIG SMS_ERRSIG /* Opération sur sémaphore interrompue par un signal */
#define DSS_ERRDLL -6 /* Problème de chargement dynamique de librairie */
#define DS_ERROR(s) ((s) < 0) /* Tous les codes retour négatifs correspondent à des erreurs */
/* Indicateurs */
typedef int DST_Flags;
#define DSD_UNDEF 0
/* Flags d'ouverture d'une data structure */
#define DSD_OPEN SMD_OPEN /* autorise l'ouverture d'une structure existante */
#define DSD_CREATE SMD_CREATE /* autorise la création de la structure */
#define DSD_NEW ~(DSD_OPEN|DSD_CREATE) /* crée une autre structure dans un heap existant */
/* Flags de debug sur l'ouverture de la librairie */
#define DSD_DEBUG_NONE 0 /* pour n'afficher aucun message généré par les diverses librairies */
#define DSD_DEBUG 1 /* pour afficher les messages générés par la librairie */
#define DSD_DEBUG_ALL 2 /* pour afficher les messages générés par toutes les librairies sous-jacentes */
/*------------------------------------------------------------------------------*/
/* Utilisations possibles des flags d'ouverture */
/*------------------------------------------------------------------------------*/
/* */
/* DSD_OPEN */
/* -> ouvrir une structure existante */
/* -> ne pas la créer si elle n'existe pas */
/* */
/* DSD_OPEN | DSD_CREATE */
/* -> ouvrir une structure si elle existe */
/* -> la créer si elle n'existe pas */
/* */
/* DSD_CREATE */
/* -> créer une structure */
/* -> ne pas l'ouvrir si elle existe déjà */
/* */
/* DSD_CREATE | DSD_NEW */
/* -> créer la structure si elle n'existe pas */
/* -> créer une autre structure dans le même heap si elle existe déjà */
/* */
/* DSD_NEW */
/* -> créer une autre structure dans le même heap si elle existe déjà */
/* -> ne pas la créer si elle n'existe pas */
/* */
/*------------------------------------------------------------------------------*/
/* Flags de verrouillage d'une data structure */
#define DSD_READ SMD_READ /* verrou partagé */
#define DSD_WRITE SMD_WRITE /* verrou exclusif */
/* Flags de fermeture d'une data structure */
#define DSD_CLOSE SMD_CLOSE /* pour fermer simplement la structure */
#define DSD_DESTROY SMD_DESTROY /* pour détruire la structure */
/* Masques pour récupérer des valeurs combinées */
#define DSD_MSK_OPEN(a) (DSD_OPEN & (a))
#define DSD_MSK_CREATE(a) (DSD_CREATE & (a))
#define DSD_MSK_NEW(a) (DSD_NEW & (a))
#define DSD_MSK_READ(a) (DSD_READ & (a))
#define DSD_MSK_WRITE(a) (DSD_WRITE & (a))
#define DSD_MSK_RW(a) ((DSD_READ | DSD_WRITE) & (a))
/*
On utilise le pointeur 'User' de la racine de la struture pour y
rattacher des données sur le heap sous-jacent.
*/
typedef struct {
char * Heap_Name;
char * Manager_FileName;
int OpenSemID; /* Indique le nombre de processus ayant ouvert la struture */
int Heap_Owner; /* Indique si la structure est propriétaire du heap sous-jacent */
int Valid; /* Indique si la structure est valide ou non */
} DST_RootDesc;
char DS_Error_Msg [512];
/* Définition des alias de l'API */
#ifndef DS_MODE
#define DS_MODE 0
#endif
#if DS_MODE == 2
/*
Utilisation des API sans vérification des arguments et sans verrouillage de
des data structures utilisées.
Cette configuration correspond à une utilisation optimisée mais non sécurisée
des API de la librairie.
Puisque les verrouillages ne sont pas faits systématiquement par les fonctions,
l'utilisateur veillera à verrouiller lui-même les data structures qu'il utilise.
*/
# define DS_Library_Open DS_Library_Open_I
# define DS_Library_Close DS_Library_Close_I
# define DS_Library_Stderr_Set DS_Library_Stderr_Set_I
# define DS_DataStruct_Open DS_DataStruct_Open_I
# define DS_DataStruct_Close DS_DataStruct_Close_I
# define DS_DataStruct_Reorg DS_DataStruct_Reorg_I
# define DS_DataStruct_Traverse DS_DataStruct_Traverse_I
# define DS_DataStruct_Convert DS_DataStruct_Convert_I
# define DS_DataStruct_Info_Print DS_DataStruct_Info_Print_I
# define DS_DataStruct_Print DS_DataStruct_Print_I
# define DS_DataStruct_Check DS_DataStruct_Check_I
# define DS_DataStruct_Dump DS_DataStruct_Dump_I
# define DS_DataStruct_Lock DS_DataStruct_Lock_I
# define DS_DataStruct_Unlock DS_DataStruct_Unlock_I
# define DS_Node_Root_Get DS_Node_Root_Get_I
# define DS_Node_First_Get DS_Node_First_Get_I
# define DS_Node_Last_Get DS_Node_Last_Get_I
# define DS_Node_Next_Get DS_Node_Next_Get_I
# define DS_Node_Previous_Get DS_Node_Previous_Get_I
# define DS_Node_Add DS_Node_Add_I
# define DS_Node_Remove DS_Node_Remove_I
# define DS_Node_Find DS_Node_Find_I
# define DS_Value_Alloc DS_Value_Alloc_I
# define DS_Value_Add DS_Value_Add_I
# define DS_Value_Remove DS_Value_Remove_I
# define DS_Value_Free DS_Value_Free_I
# define DS_Alloc DS_Alloc_I
# define DS_Free DS_Free_I
#elif DS_MODE == 1
/*
Utilisation des API sans vérification des arguments mais avec
verrouillage systématique des data structures utilisées.
*/
# define DS_Library_Open DS_Library_Open_L
# define DS_Library_Close DS_Library_Close_L
# define DS_Library_Stderr_Set DS_Library_Stderr_Set_L
# define DS_DataStruct_Open DS_DataStruct_Open_L
# define DS_DataStruct_Close DS_DataStruct_Close_L
# define DS_DataStruct_Reorg DS_DataStruct_Reorg_L
# define DS_DataStruct_Traverse DS_DataStruct_Traverse_L
# define DS_DataStruct_Convert DS_DataStruct_Convert_L
# define DS_DataStruct_Info_Print DS_DataStruct_Info_Print_L
# define DS_DataStruct_Print DS_DataStruct_Print_L
# define DS_DataStruct_Check DS_DataStruct_Check_L
# define DS_DataStruct_Dump DS_DataStruct_Dump_L
# define DS_DataStruct_Lock DS_DataStruct_Lock_L
# define DS_DataStruct_Unlock DS_DataStruct_Unlock_L
# define DS_Node_Root_Get DS_Node_Root_Get_L
# define DS_Node_First_Get DS_Node_First_Get_L
# define DS_Node_Last_Get DS_Node_Last_Get_L
# define DS_Node_Next_Get DS_Node_Next_Get_L
# define DS_Node_Previous_Get DS_Node_Previous_Get_L
# define DS_Node_Add DS_Node_Add_L
# define DS_Node_Remove DS_Node_Remove_L
# define DS_Node_Find DS_Node_Find_L
# define DS_Value_Alloc DS_Value_Alloc_L
# define DS_Value_Add DS_Value_Add_L
# define DS_Value_Remove DS_Value_Remove_L
# define DS_Value_Free DS_Value_Free_L
# define DS_Alloc DS_Alloc_L
# define DS_Free DS_Free_L
#else
/*
Utilisation des API avec vérification des arguments
et avec verrouillage des data structures utilisées.
*/
# define DS_Library_Open DS_Library_Open_CL
# define DS_Library_Close DS_Library_Close_CL
# define DS_Library_Stderr_Set DS_Library_Stderr_Set_CL
# define DS_DataStruct_Open DS_DataStruct_Open_CL
# define DS_DataStruct_Close DS_DataStruct_Close_CL
# define DS_DataStruct_Reorg DS_DataStruct_Reorg_CL
# define DS_DataStruct_Traverse DS_DataStruct_Traverse_CL
# define DS_DataStruct_Convert DS_DataStruct_Convert_CL
# define DS_DataStruct_Info_Print DS_DataStruct_Info_Print_CL
# define DS_DataStruct_Print DS_DataStruct_Print_CL
# define DS_DataStruct_Check DS_DataStruct_Check_CL
# define DS_DataStruct_Dump DS_DataStruct_Dump_CL
# define DS_DataStruct_Lock DS_DataStruct_Lock_CL
# define DS_DataStruct_Unlock DS_DataStruct_Unlock_CL
# define DS_Node_Root_Get DS_Node_Root_Get_CL
# define DS_Node_First_Get DS_Node_First_Get_CL
# define DS_Node_Last_Get DS_Node_Last_Get_CL
# define DS_Node_Next_Get DS_Node_Next_Get_CL
# define DS_Node_Previous_Get DS_Node_Previous_Get_CL
# define DS_Node_Add DS_Node_Add_CL
# define DS_Node_Remove DS_Node_Remove_CL
# define DS_Node_Find DS_Node_Find_CL
# define DS_Value_Alloc DS_Value_Alloc_CL
# define DS_Value_Add DS_Value_Add_CL
# define DS_Value_Remove DS_Value_Remove_CL
# define DS_Value_Free DS_Value_Free_CL
# define DS_Alloc DS_Alloc_CL
# define DS_Free DS_Free_CL
#endif
/*------------------------------------------------------------------------------*/
/* Ouverture d'une instance de la librairie */
/*------------------------------------------------------------------------------*/
/* (I) Instance : numéro de l'instance de la librairie */
/* (I) Context : nom du contexte */
/* (I) Debug_Mode : mode d'affichage des messages d'erreur */
/*------------------------------------------------------------------------------*/
DST_Status DS_Library_Open_I ( int Instance, const char * Context, \
DST_Flags Debug_Mode );
DST_Status DS_Library_Open_L ( int Instance, const char * Context, \
DST_Flags Debug_Mode );
DST_Status DS_Library_Open_CL ( int Instance, const char * Context, \
DST_Flags Debug_Mode );
/*------------------------------------------------------------------------------*/
/* Fermeture de l'instance de la librairie */
/*------------------------------------------------------------------------------*/
DST_Status DS_Library_Close_I ( void );
DST_Status DS_Library_Close_L ( void );
DST_Status DS_Library_Close_CL ( void );
/*------------------------------------------------------------------------------*/
/* Définition de la sortie standard des messages d'erreur de la librairie */
/*------------------------------------------------------------------------------*/
/* (I) Out : flux de sortie des messages d'erreur */
/*------------------------------------------------------------------------------*/
DST_Status DS_Library_Stderr_Set_I ( FILE * Out );
DST_Status DS_Library_Stderr_Set_L ( FILE * Out );
DST_Status DS_Library_Stderr_Set_CL ( FILE * Out );
/*------------------------------------------------------------------------------*/
/* Création / ouverture d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) DS_Name : nom de la structure */
/* (O) Root : adresse du pointeur sur la racine de la structure */
/* (I) Type : type de la structure de données */
/* (I) Manager_FileName : nom du fichier qui définit les fonctions manager */
/* (I) Segment_Size : taille ds segments du heap sous-jacent */
/* (I) Open_Mode : mode d'ouverture de la structure */
/* (I) Own_Value : indique si la structure possède ses valeurs */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Open_I ( const char * DS_Name, NDT_Root ** Root,\
NDT_DataStruct_Type Type, const char * Manager_FileName, \
size_t Segment_Size, DST_Flags Open_Mode, int Own_Value );
DST_Status DS_DataStruct_Open_L ( const char * DS_Name, NDT_Root ** Root,\
NDT_DataStruct_Type Type, const char * Manager_FileName, \
size_t Segment_Size, DST_Flags Open_Mode, int Own_Value );
DST_Status DS_DataStruct_Open_CL ( const char * DS_Name, NDT_Root ** Root,\
NDT_DataStruct_Type Type, const char * Manager_FileName, \
size_t Segment_Size, DST_Flags Open_Mode, int Own_Value );
/*------------------------------------------------------------------------------*/
/* Verrouillage d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure */
/* (I) Lock_Mode : type de verrou à poser sur la structure */
/* (O) Locked : verrou effectif (TRUE ou FALSE) */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Lock_I ( NDT_Root * Root, DST_Flags Lock_Mode, \
int * Locked );
DST_Status DS_DataStruct_Lock_L ( NDT_Root * Root, DST_Flags Lock_Mode, \
int * Locked );
DST_Status DS_DataStruct_Lock_CL ( NDT_Root * Root, DST_Flags Lock_Mode, \
int * Locked );
/*------------------------------------------------------------------------------*/
/* Déverrouillage d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Unlock_I ( NDT_Root * Root );
DST_Status DS_DataStruct_Unlock_L ( NDT_Root * Root );
DST_Status DS_DataStruct_Unlock_CL ( NDT_Root * Root );
/*------------------------------------------------------------------------------*/
/* Fermeture d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Close_Mode : mode de fermeture de la structure (destruction ou non) */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Close_I ( NDT_Root * Root, DST_Flags Close_Mode );
DST_Status DS_DataStruct_Close_L ( NDT_Root * Root, DST_Flags Close_Mode );
DST_Status DS_DataStruct_Close_CL ( NDT_Root * Root, DST_Flags Close_Mode );
/*------------------------------------------------------------------------------*/
/* Affiche les informations d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root: pointeur sur la racine de la structure de données */
/* (I) Out : flux de sortie de l'affichage */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Info_Print_I ( NDT_Root * Root, FILE * Out );
DST_Status DS_DataStruct_Info_Print_L ( NDT_Root * Root, FILE * Out );
DST_Status DS_DataStruct_Info_Print_CL ( NDT_Root * Root, FILE * Out );
/*------------------------------------------------------------------------------*/
/* Réorganisation d'une structure de données : */
/* - ordonnancement d'une liste non ordonnée */
/* - réquilibrage d'un arbre non auto-équilibré */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Reorg_I ( NDT_Root * Root );
DST_Status DS_DataStruct_Reorg_L ( NDT_Root * Root );
DST_Status DS_DataStruct_Reorg_CL ( NDT_Root * Root );
/*------------------------------------------------------------------------------*/
/* Parcours de tous les noeuds d'une structure de données et exécution d'une */
/* commande sur chacun d'eux */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Command : Commande à exécuter sur chaque noeud traversé */
/* (I) Data : pointeur de données utilisateur */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Traverse_I ( NDT_Root * Root, NDT_Command Command, \
void * Data );
DST_Status DS_DataStruct_Traverse_L ( NDT_Root * Root, NDT_Command Command, \
void * Data );
DST_Status DS_DataStruct_Traverse_CL ( NDT_Root * Root, NDT_Command Command, \
void * Data );
/*------------------------------------------------------------------------------*/
/* Conversion d'une structure de données d'un type en un autre */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Target_Type : type de structure cible */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Convert_I ( NDT_Root * Root, \
NDT_DataStruct_Type Target_Type );
DST_Status DS_DataStruct_Convert_L ( NDT_Root * Root, \
NDT_DataStruct_Type Target_Type );
DST_Status DS_DataStruct_Convert_CL ( NDT_Root * Root, \
NDT_DataStruct_Type Target_Type );
/*------------------------------------------------------------------------------*/
/* Affichage de la valeur de tous les noeuds d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Out : flux de sortie */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Print_I ( NDT_Root * Root, FILE * Out );
DST_Status DS_DataStruct_Print_L ( NDT_Root * Root, FILE * Out );
DST_Status DS_DataStruct_Print_CL ( NDT_Root * Root, FILE * Out );
/*------------------------------------------------------------------------------*/
/* Fonction de vérification / réparation d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure */
/* (O) Nb_Detected : pointeur sur le nombre d'erreurs détectées */
/* (O) Nb_Corrected : pointeur sur le nombre d'erreurs corrigées */
/* (I) Out : flux de sortie du rapport */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Check_I ( NDT_Root * Root, int * Nb_Detected, \
int * Nb_Corrected, FILE * Out );
DST_Status DS_DataStruct_Check_L ( NDT_Root * Root, int * Nb_Detected, \
int * Nb_Corrected, FILE * Out );
DST_Status DS_DataStruct_Check_CL ( NDT_Root * Root, int * Nb_Detected, \
int * Nb_Corrected, FILE * Out );
/*------------------------------------------------------------------------------*/
/* Affichage de la structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure */
/* (I) Out : flux de sortie */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Dump_I ( NDT_Root * Root, FILE * Out );
DST_Status DS_DataStruct_Dump_L ( NDT_Root * Root, FILE * Out );
DST_Status DS_DataStruct_Dump_CL ( NDT_Root * Root, FILE * Out );
/*------------------------------------------------------------------------------*/
/* Récupération du premier noeud d'une structure */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine dont on cherche le premier noeud */
/* (O) Node : pointeur sur le noeud à récupérer */
/*------------------------------------------------------------------------------*/
DST_Status DS_Node_First_Get_I ( NDT_Root * Root, NDT_Node ** Node );
DST_Status DS_Node_First_Get_L ( NDT_Root * Root, NDT_Node ** Node );
DST_Status DS_Node_First_Get_CL ( NDT_Root * Root, NDT_Node ** Node );
/*------------------------------------------------------------------------------*/
/* Récupération du dernier noeud d'une structure */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine dont on cherche le dernier noeud */
/* (O) Node : pointeur sur le noeud à récupérer */
/*------------------------------------------------------------------------------*/
DST_Status DS_Node_Last_Get_I ( NDT_Root * Root, NDT_Node ** Node );
DST_Status DS_Node_Last_Get_L ( NDT_Root * Root, NDT_Node ** Node );
DST_Status DS_Node_Last_Get_CL ( NDT_Root * Root, NDT_Node ** Node );
/*------------------------------------------------------------------------------*/
/* Récupération du noeud suivant */
/*------------------------------------------------------------------------------*/
/* (I) Node : pointeur sur le noeud dont on cherche le suivant */
/* (O) Next_Node : pointeur sur le noeud suivant */
/*------------------------------------------------------------------------------*/
DST_Status DS_Node_Next_Get_I ( NDT_Node * Node, NDT_Node ** Next_Node );
DST_Status DS_Node_Next_Get_L ( NDT_Node * Node, NDT_Node ** Next_Node );
DST_Status DS_Node_Next_Get_CL ( NDT_Node * Node, NDT_Node ** Next_Node );
/*------------------------------------------------------------------------------*/
/* Récupération du noeud précédant */
/*------------------------------------------------------------------------------*/
/* (I) Node : pointeur sur le noeud dont on cherche le précédant */
/* (O) Prev_Node : pointeur sur le noeud précédant */
/*------------------------------------------------------------------------------*/
DST_Status DS_Node_Previous_Get_I ( NDT_Node * Node, NDT_Node ** Prev_Node );
DST_Status DS_Node_Previous_Get_L ( NDT_Node * Node, NDT_Node ** Prev_Node );
DST_Status DS_Node_Previous_Get_CL ( NDT_Node * Node, NDT_Node ** Prev_Node );
/*------------------------------------------------------------------------------*/
/* Ajout d'un noeud à une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Node : pointeur sur le noeud à ajouter */
/*------------------------------------------------------------------------------*/
DST_Status DS_Node_Add_I ( NDT_Root * Root, NDT_Node * Node );
DST_Status DS_Node_Add_L ( NDT_Root * Root, NDT_Node * Node );
DST_Status DS_Node_Add_CL ( NDT_Root * Root, NDT_Node * Node );
/*------------------------------------------------------------------------------*/
/* Suppression d'un noeud dans une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Node: pointeur sur le noeud à supprimer de la structure de données */
/*------------------------------------------------------------------------------*/
DST_Status DS_Node_Remove_I ( NDT_Node * Node );
DST_Status DS_Node_Remove_L ( NDT_Node * Node );
DST_Status DS_Node_Remove_CL ( NDT_Node * Node );
/*------------------------------------------------------------------------------*/
/* Recherche un noeud dans un arbre et retourne le pointeur sur le noeud */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de l'abre */
/* (O) Node : adresse du pointeur sur le noeud à récuperer */
/* (I) Value : pointeur sur la valeur à rechercher */
/* (I) Data : pointeur de données */
/*------------------------------------------------------------------------------*/
DST_Status DS_Node_Find_I ( NDT_Root * Root, NDT_Node ** Node, \
void * Value, void * Data );
DST_Status DS_Node_Find_L ( NDT_Root * Root, NDT_Node ** Node, \
void * Value, void * Data );
DST_Status DS_Node_Find_CL ( NDT_Root * Root, NDT_Node ** Node, \
void * Value, void * Data );
/*------------------------------------------------------------------------------*/
/* Allocation d'une valeur d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (O) Value : adresse d'un pointeur sur la valeur à allouer */
/* (I) ... : arguments relatifs à l'allocation de la valeur */
/*------------------------------------------------------------------------------*/
DST_Status DS_Value_Alloc_I ( NDT_Root * Root, void ** Value, ... );
DST_Status DS_Value_Alloc_L ( NDT_Root * Root, void ** Value, ... );
DST_Status DS_Value_Alloc_CL ( NDT_Root * Root, void ** Value, ... );
/*------------------------------------------------------------------------------*/
/* Ajout d'une valeur à une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Value : pointeur sur la valeur à ajouter */
/*------------------------------------------------------------------------------*/
DST_Status DS_Value_Add_I ( NDT_Root * Root, void * Value );
DST_Status DS_Value_Add_L ( NDT_Root * Root, void * Value );
DST_Status DS_Value_Add_CL ( NDT_Root * Root, void * Value );
/*------------------------------------------------------------------------------*/
/* Suppression du premier noeud correspondant à une valeur donnée */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Reference_Value : pointeur sur la valeur de référence */
/* (I) Removed_Value : adresse d'un pointeur sur la valeur supprimée */
/*------------------------------------------------------------------------------*/
DST_Status DS_Value_Remove_I ( NDT_Root * Root, void * Reference_Value, \
void ** Removed_Value);
DST_Status DS_Value_Remove_L ( NDT_Root * Root, void * Reference_Value, \
void ** Removed_Value);
DST_Status DS_Value_Remove_CL ( NDT_Root * Root, void * Reference_Value, \
void ** Removed_Value);
/*------------------------------------------------------------------------------*/
/* Désallocation d'une valeur d'une structure de données */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Value : pointeur sur la valeur à désallouer */
/*------------------------------------------------------------------------------*/
DST_Status DS_Value_Free_I ( NDT_Root * Root, void * Value );
DST_Status DS_Value_Free_L ( NDT_Root * Root, void * Value );
DST_Status DS_Value_Free_CL ( NDT_Root * Root, void * Value );
/*------------------------------------------------------------------------------*/
/* Allocation de mémoire pour une structure de données : */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Size : taille mémoire à allouer */
/* (O) Ptr : adresse du pointeur sur la zone de données allouée */
/*------------------------------------------------------------------------------*/
DST_Status DS_Alloc_I ( NDT_Root * Root, size_t Size, void ** Ptr );
DST_Status DS_Alloc_L ( NDT_Root * Root, size_t Size, void ** Ptr );
DST_Status DS_Alloc_CL ( NDT_Root * Root, size_t Size, void ** Ptr );
/*------------------------------------------------------------------------------*/
/* Désallocation d'une ressource pour une structure de données : */
/*------------------------------------------------------------------------------*/
/* (I) Root : pointeur sur la racine de la structure de données */
/* (I) Ptr : pointeur sur la zone à désallouer */
/*------------------------------------------------------------------------------*/
DST_Status DS_Free_I ( NDT_Root * Root, void * Ptr );
DST_Status DS_Free_L ( NDT_Root * Root, void * Ptr );
DST_Status DS_Free_CL ( NDT_Root * Root, void * Ptr );
#ifdef __cplusplus
}
#endif
#endif

737
lib/libdatastr.3 Normal file
View File

@ -0,0 +1,737 @@
'\" t
.\" @(#)LIBDATASTR.3 99/10/12 SMI;
.TH LIBDATASTR 3 "10 Oct 1999"
.SH NOM
LIBDATASTR (librairie de structure de donnees a base de noeuds dans un contexte de memoire partagee)
.SH SYNOPSIS
.LP
.BI "cc [flag ...] file ... -lver -ldl -lnode -lshmem -ldatastr [library ...]"
.LP
.BI "#include <datastr.h>"
.LP
.BI "DST_Status DS_Library_Open ( int " Instance " , char * " Context_Name ", DST_Flags " Debug_Mode " );"
.LP
.BI "DST_Status DS_Library_Close ( " void " );
.LP
.BI "DST_Status DS_Library_Stderr_Set ( FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Open ( char * " DS_Name ", NDT_Root ** " Root ", ND_DataStruct_Type " DS_Type ", char * " Manager_File_Name ", size_t " Segment_Size ", DST_Flags " Open_Mode ", int " Own_Values " );"
.LP
.BI "DST_Status DS_DataStruct_Lock ( NDT_Root * " Root ", DST_Flags " Lock_Mode " , int * " Locked " );"
.LP
.BI "DST_Status DS_DataStruct_Unlock ( NDT_Root * " Root " );"
.LP
.BI "DST_Status DS_DataStruct_Close ( NDT_Root * " Root ", DST_Flags " Close_Mode " );"
.LP
.BI "DST_Status DS_DataStruct_Info_Print ( NDT_Root * " Root ", FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Reorg ( NDT_Root * " Root ");"
.LP
.BI "DST_Status DS_DataStruct_Traverse ( NDT_Root * " Root ", NDT_Command " Command ", void * " Data " );"
.LP
.BI "DST_Status DS_DataStruct_Convert ( NDT_Root * " Root ", NDT_DataStruct_Type " Target_Type " );"
.LP
.BI "DST_Status DS_DataStruct_Print ( NDT_Root * " Root ", FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Check ( NDT_Root * " Root ", int * " Nb_Detected ", * int " Nb_Corrected ", FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Dump ( NDT_Root * " Root ", FILE * " Out " );"
.LP
.BI "DST_Status DS_Node_First_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.BI "DST_Status DS_Node_Last_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.BI "DST_Status DS_Node_Next_Get ( NDT_Node * " Node ", NDT_Node ** " Next_Node " );"
.LP
.BI "DST_Status DS_Node_Previous_Get ( NDT_Node * " Node ", NDT_Node ** " Prev_Node " );"
.LP
.BI "DST_Status DS_Node_Add ( NDT_Root * " Root ", ND_Node * " Node " );"
.LP
.BI "DST_Status DS_Node_Remove (ND_Node * " Node " );"
.LP
.BI "DST_Status DS_Node_Find ( NDT_Root * " Root ", NDT_Node ** " Node ", void * " To_Search ", void * " Data " );"
.LP
.BI "DST_Status DS_Value_Alloc ( NDT_Root * " Root ", void ** " Value ", ... );"
.LP
.BI "DST_Status DS_Value_Add ( NDT_Root * " Root ", void * " To_Add " );"
.LP
.BI "DST_Status DS_Value_Remove ( NDT_Root * " Root ", void * " Reference_Value ", void ** " Removed_Value " );"
.LP
.BI "DST_Status DS_Value_Free ( NDT_Root * " Root ", void * " Value " );"
.LP
.BI "DST_Status DS_Alloc ( NDT_Root * " Root ", size_t " Size ", void ** " Ptr " );"
.LP
.BI "DST_Status DS_Free ( NDT_Root * " Root ", void * " Ptr " );"
.LP
.SH DESCRIPTION
.LP
La librairie LIBDATASTR implemente des structures de donnees a base de noeuds dans
un contexte de memoire partagee.
.LP
Elle est basee sur deux librairies sous-jacentes :
.LP
.RS 3
- LIBNODE
: gestion de structure a base de noeuds
.LP
- LIBSHMEM
: gestion de contextes de memoire partagee
.RS -3
.LP
La librairie LIBDATASTR gere les memes types de structure de donnees que la librairie LIBNODE
et propose les memes fonctionnalites que cette derniere.
.LP
L'utilisateur est donc prie de se referer a la documentation de la librairie LIBNODE
pour toute information relative aux structures de donnees manipulees.
.LP
La librairie LIBDATASTR propose une interface (API) tres similaire a celle de la librairie LIBNODE
.
.LP
Toutefois, une premiere difference reside dans le fait que chaque structure de donnees possede un nom.
Chaque structure pourra ainsi etre facilement identifiee dans la base de memoire partagee.
.LP
Par ailleurs, puisque chaque structure gere des valeurs qui lui sont propres, les fonctions de
manipulation (Manager, Allocator, Desallocator) de ces valeurs doivent aussi etre partageables.
C'est pourquoi chaque processus initiateur d'une structure doit fournir un fichier qui definit ces fonctions.
Le nom de ce fichier (.so) sera rattache a la racine de la structure lors de sa creation.
Ainsi, tout processus voulant acceder a une structure dont il ne connait pas les valeurs n'aura qu'a charger dynamiquement ce fichier pour pouvoir les manipuler.
.LP
.SH FONCTIONS
.LP
.BI "DST_Status DS_Library_Open ( int " Instance " , char * " Context_Name ", DST_Flags " Debug_Mode " );"
.RS 3
.LP
Permet d'acceder aux ressources de la librairie LIBDATASTR.
Elle permet notamment d'acceder a la base de memoire partagee d'une instance donnee (voir la librairie LIBSHMEM) et de manipuler des structures de donnees dans un contexte donne.
.LP
Cette fonction attend les arguments suivants :
.LP
.RS 3
- (In)
.I Instance
: designe le numero de l'instance a ouvrir.
.LP
Si cet argument est NULL, alors c'est la variable d'environnement $PROFILE qui definira le numero de l'instance.
.LP
- (In)
.I Context_Name
: designe le nom du contexte a utiliser.
.LP
- (In)
.I Debug_Mode
: mode d'affichage des messages d'erreur :
.LP
.RS 3
-
.B DS_DEBUG_NONE
: aucun message d'erreur n'est affiche
.LP
-
.B DS_DEBUG
: les messages d'erreur generes par la librairie LIBDATASTR sont affiches sur la sortie standard d'erreur
.LP
-
.B DS_DEBUG_ALL
: les messages d'erreur generes par toutes les librairies sous-jacentes a la LIBDATASTR sont affiches sur la sortie standard d'erreur
.RS -3
.LP
.RS -3
.I Rappels
: la notion de contexte permet de creer plusieurs environnements parfaitement distincts au sein d'une meme instance.
.LP
.I Important
: cette fonction devra etre systematiquement appelee au debut de chaque programme utilisant la librairie LIBDATASTR.
.LP
Cette fonction echouera si l'instance de la librairie LIBSHMEM n'a pas ete creee.
.LP
.RS -3
.BI "DST_Status DS_Library_Close ( " void " );"
.RS 3
.LP
Permet de fermer les ressources de l'instance de la librairie LIBDATASTR.
.I NB
: cette fonction etre systematiquement appelee a la fin de chaque programme utilisant la librairie LIBDATASTR.
.LP
.RS -3
.BI "DST_Status DS_Library_Stderr_Set ( FILE * " Out " );"
.LP
.RS 3
Cette fonction permet de definir
.I Out
comme la sortie standard des messages d'erreur de la librarie.
.RS -3
.LP
.BI "DST_Status DS_DataStruct_Open ( char * " DS_Name ", NDT_Root ** " Root ", ND_DataStruct_Type " DS_Type ", char * " Manager_File_Name ", size_t " Segment_Size ", DST_Flags " Open_Mode ", int " Own_Values " );"
.RS 3
.LP
Cette fonction permet d'ouvrir ou de creer une structure de donnees.
.LP
La fonction doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I DS_Name
: le nom de la structure de donnees
.LP
* (Out)
.I Root
: l'adresse du pointeur sur la racine de la structure de donnees
.LP
* (In)
.I DS_Type
: le type de la nouvelle structure de donnees.
Dans le cas de l'ouverture d'une structure de donnees existante, cet argument n'est pas pris en compte.
.LP
* (In)
.I Manager_File_Name
: le nom du fichier (.so) definissant les fonctions manager de la structure.
Dans le cas de l'ouverture d'une structure de donnees existante, cet argument n'est pas pris en compte.
.LP
* (In)
.I Segment_Size
: la taille des segments de donnees du heap sous-jacent.
Bien entendu, cet argument n'est pris en compte que lors de la creation d'une structure dans un nouveau heap.
.LP
* (In)
.I Open_Mode
: le mode d'ouverture pouvant prendre les valeurs suivantes combinees :
.LP
* (In)
.I Own_Values
: indique si la data structure est proprietaire de ses valeurs (TRUE ou FALSE)
.LP
.RS 3
-
.B DSD_OPEN
pour autoriser l'ouverture d'une structure existante.
.LP
-
.B DSD_CREATE
pour autoriser la creation de la structure si elle n'existe pas.
.LP
-
.B DSD_NEW
pour autoriser la creation d'une autre structure dans le meme heap si elle existe deja.
.RS -3
.LP
.RS -3
.I NB
: une fois qu'une structure de donnees est ouverte, l'utilisateur est assure de son existence, au moins jusqu'a ce que celle-ci soit fermee.
.LP
.I Information
: toutes les structures de donnees manipulees sont basees sur des heaps dont les noms seront prefixes par "datastr" afin d'indiquer que ces heaps ont ete crees par l'intermediaire de cette librairie.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Lock ( NDT_Root * " Root ", DST_Flags " Lock_Mode " , int * " Locked " );"
.RS 3
.LP
Cette fonction permet de verrouiller une structure de donnees.
.LP
La fonction doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Lock_Mode
: le mode de verrouillage (
.B DSD_READ
ou
.B DSD_WRITE
)
.LP
* (Out)
.I Locked
: un pointeur sur un indicateur de verrouillage qui prendra la valeur :
.LP
.RS 3
- TRUE si le verrouillage est effectif
.LP
- FALSE si la structure etait deja verrouillee dans ce mode
.RS -3
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Unlock ( NDT_Root * " Root " );"
.RS 3
.LP
Cette fonction permet de deverrouiller une structure de donnees.
.LP
L'argument
.I Root
est un pointeur sur la racine de la structure de donnees a deverrouiller.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Close ( NDT_Root * " Root ", DST_Flags " Close_Mode " );"
.RS 3
.LP
Cette fonction permet de fermer ou de detruire une structure de donnees.
.LP
La fonction doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Close_Mode
: le mode de fermeture (
.B DSD_CLOSE
ou
.B DSD_DESTROY
)
.RS -3
.LP
.I NB
: une structure de donnees ne pourra etre detruite que si elle n'est plus accedee par aucun autre processus.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Info_Print ( NDT_Root * " Root ", FILE * " Out " );"
.RS 3
.LP
Cette fonction permet d'afficher les informations d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees.
.LP
* (In)
.I Out
: le flux de sortie de l'affichage.
.LP
.RS -3
.RS -3
.BI "DST_Status DS_DataStruct_Traverse ( NDT_Root * " Root ", NDT_Command " Command ", void * " Data " );"
.RS 3
.LP
Cette fonction permet de parcourir tous les noeuds d'une structure de donnees avec execution d'une commande sur chacun d'eux.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: le pointeur sur la racine de la structure de donnees a parcourir.
.LP
* (In)
.I Command
: la commande a executer sur chaque noeud traverse
.LP
* (In)
.I Data
: un pointeur de donnees propre a la commande
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Reorg ( NDT_Root * " Root ");
.RS 3
.LP
Cette fonction permet de reorganiser les donnees d'une structure (tri pour une liste, reequilibrage pour un arbre).
.LP
.I Root
est un pointeur sur la racine de la structure de donnees a reorganiser.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Convert ( NDT_Root * " Root ", NDT_DataStruct_Type " Target_Type " );"
.RS 3
.LP
Cette fonction permet de convertir une structure de donnees d'un type en un autre.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees a convertir.
.LP
* (In)
.I Target_Type
: le type de la structure cible
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Print ( NDT_Root * " Root ", FILE * " Out " );"
.RS 3
.LP
Cette fonction permet d'afficher toutes les valeurs des noeuds d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: le pointeur sur la racine de la structure de donnees a afficher.
.LP
* (In)
.I Out
: un pointeur sur le flux de sortie
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Check ( NDT_Root * " Root ", int * " Nb_Detected ", * int " Nb_Corrected ", FILE * " Out " );"
.RS 3
.LP
Cette fonction realise des controles d'integrite sur une structure de donnees :
.LP
.RS 3
- controle du heap sous-jacent a la structure
.LP
- controle de la structure de noeuds
.LP
.RS -3
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees a corriger.
.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.
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Dump ( NDT_Root * " Root ", FILE * " Out " );"
.RS 3
.LP
Cette fonction permet d'afficher une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees a corriger.
.LP
* (In)
.I Out
: un pointeur sur le flux de sortie de l'affichage
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_First_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le premier noeud d'une structure.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure
.LP
* (Out)
.I Node
: l'adresse d'un pointeur sur le premier noeud a recuperer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Last_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le dernier noeud d'une structure.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure
.LP
* (Out)
.I Node
: un pointeur sur le dernier noeud a recuperer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Next_Get ( NDT_Node * " Node ", NDT_Node ** " Next_Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le noeud qui suit immediatement un noeud particulier.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Node
: un pointeur sur le noeud de reference
.LP
* (Out)
.I Next_Node
: l'adresse d'un pointeur sur le noeud qui suit le noeud de reference
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Previous_Get ( NDT_Node * " Node ", NDT_Node ** " Prev_Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le noeud qui precede immediatement un noeud particulier.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Node
: un pointeur sur le noeud de reference
.LP
* (Out)
.I Prev_Node
: l'adresse d'un pointeur sur le noeud qui precede le noeud de reference
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Add ( NDT_Root * " Root ", ND_Node * " Node " );"
.RS 3
.LP
Cette fonction permet d'ajouter un noeud a une structure.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Node
: un pointeur sur le noeud a ajouter
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Remove (ND_Node * " Node " );"
.RS 3
.LP
Cette fonction permet de supprimer le noeud d'une structure de donnees.
.LP
.I Node
est un pointeur sur le noeud a supprimer.
.LP
.I NB
: le noeud supprime n'est pas detruit mais simplement detache de la structure
.LP
.RS -3
.BI "DST_Status DS_Node_Find ( NDT_Root * " Root ", NDT_Node ** " Node ", void * " To_Search ", void * " Data " );"
.RS 3
.LP
Cette fonction permet de rechercher dans une structure de donnees le premier noeud correspondant a une valeur.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (Out)
.I Node
: l'adresse d'un pointeur sur le noeud resultat
.LP
* (In)
.I To_Search
: un pointeur sur la valeur a rechercher
.LP
* (In)
.I Data
: un pointeur de donnees a passer au manager pour la recherche
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Value_Alloc ( NDT_Root * " Root ", void ** " Value ", ... );"
.LP
.RS 3
Cette fonction permet d'allouer une valeur pour une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (Out)
.I Value
: l'adresse d'un pointeur sur la valeur a allouer
.LP
* (In)
.I ...
: des arguments supplementaires pour l'allocation de la valeur
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Value_Add ( NDT_Root * " Root ", void * " To_Add " );"
.RS 3
.LP
Cette fonction permet d'ajouter une valeur a une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I To_Add
: un pointeur sur la valeur a ajouter
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Value_Remove ( NDT_Root * " Root ", void * " Reference_Value ", void ** " Removed_Value " );"
.RS 3
.LP
Cette fonction permet de supprimer une valeur d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.RS 3
.LP
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Reference_Value
: un pointeur sur la valeur de reference
.LP
* (Out)
.I Removed_Value
: l'adresse d'un pointeur sur la valeur du noeud supprime
.LP
.RS -3
.I NB
: la suppression d'un noeud implique son retrait de la structure et sa desallocation.
.LP
.RS -3
.BI "DST_Status DS_Value_Free ( NDT_Root * " Root ", void * " Value " );"
.LP
.RS 3
Cette fonction permet de desallouer une valeur faisant partie d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Value
: un pointeur sur la valeur a desallouer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Alloc ( NDT_Root * " Root ", size_t " Size ", void ** " Ptr " );"
.RS 3
.LP
Cette fonction permet d'allouer de la memoire dans le meme contexte (meme heap) qu'une structure de donnees.
Elle sera utilisee notamment pour l'allocation des valeurs rattachees aux noeuds de la structure.
.LP
Elle doit recevoir les arguments suivants :
.RS 3
.LP
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Size
: la taille de la memoire a allouer.
.LP
* (Out)
.I Ptr
: l'adresse d'un pointeur sur la zone a allouer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Free ( NDT_Root * " Root ", void * " Ptr " );"
.RS 3
.LP
Cette fonction permet de liberer de la memoire qui a ete allouee dans le meme contexte qu'une structure de donnees (meme heap).
Elle sera utilisee notamment pour desallouer des valeurs rattachees aux noeuds de la structure.
.LP
Elle doit recevoir les arguments suivants :
.RS 3
.LP
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Ptr
: un pointeur sur la zone a desallouer.
.RS -3
.LP
.SH "CODES RETOUR"
.LP
Toutes les fonctions de la librairie LIBDATASTR retournent une valeur de type
.B DST_Status
:
.LP
.RS 3
-
.B DSS_OK
: la fonction s'est correctement executee et a produit un resultat
.LP
-
.B DSS_KO
: la fonction s'est correctement executee mais n'a pas produit de resultat
.LP
-
.B DSS_ERRAPI
: la fonction a ete appelee avec des arguments de valeur incorrecte
.LP
-
.B DSS_ERRMEM
: la fonction ne s'est pas correctement executee pour un probleme d'allocation memoire
.LP
-
.B DSS_ERRSHM
: la fonction ne s'est pas correctement executee pour un probleme relatif a la memoire partagee
.LP
-
.B DSS_ERRSIG
: une operation sur semaphore a ete interrompue par un signal
.LP
-
.B DSS_ERRSEM
: la fonction ne s'est pas correctement executee pour un probleme relatif a l'utilisation des semaphores
.LP
-
.B DSS_ERRDLL
: la fonction ne s'est pas correctement executee pour un probleme de chargement dynamique d'objet
.LP
.RS -3
.I NB
: la macro
.B DS_ERROR()
permet de tester si un code retour correspond a une erreur.
.LP
En cas d'erreur, la variable
.B DS_Error_Msg
contient un message du type :
.LP
.RS 3
Error <Nom fonction> : <message d'erreur>
.RS -3
.LP
.SH VOIR AUSSI
.B libnode
(3)
,
.B libshmem
(3)

3071
lib/libdatastr.c Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
lib/libdatastr.doc Normal file
View File

Binary file not shown.

97
lib/libdatastr.h Normal file
View File

@ -0,0 +1,97 @@
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <dlfcn.h>
#include <stdarg.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/sem.h>
#include <sys/ipc.h>
#include <ver.h>
#include <node.h>
#include <datastr.h>
extern char * strdup ( const char * );
/* Compteur d'ouverture de la librairie */
unsigned int DS_Open_Counter = 0;
/* Tous les heaps créés via la librairie LIBDATASTR seront préfixés par le nom suivant */
#define DS_PREFIX "DATASTR"
/* Flux de sortie des messages d'erreur */
FILE * DS_stderr;
/*
Pour gérer les ouvertures, fermetures ou destructions d'une data structure, on
opère sur un sémaphore (OpenSemID) rattaché à la description de la structure
qui comptabilise les processus ayant ouvert la data structure.
*/
struct sembuf DS_SemOp_Open [1] = { {0, 1, SEM_UNDO|IPC_NOWAIT} };
struct sembuf DS_SemOp_Close [1] = { {0, -1, SEM_UNDO|IPC_NOWAIT} };
struct sembuf DS_SemOp_Destroy [2] = { {0, -1, SEM_UNDO|IPC_NOWAIT}, {0, 0, SEM_UNDO|IPC_NOWAIT} };
typedef union semun {
int val;
struct semid_ds * buf;
unsigned short int * array;
} semun;
/* Liste des data structure ouvertes par le processus courant */
NDT_Root * OpenedDS_List;
typedef struct {
NDT_Root * Root;
char * Name;
} DST_DataStruct;
/*------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------*/
/* Fonctions privées de la librairie */
/*------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------*/
/* Création d'un sémaphore pour gérer l'ouverture d'une data structure */
/*------------------------------------------------------------------------------*/
DST_Status DS_Semaphore_Create (NDT_Root * Root);
/*------------------------------------------------------------------------------*/
/* Opération sur un sémaphore */
/*------------------------------------------------------------------------------*/
DST_Status DS_Semaphore_Operate (int, struct sembuf *, unsigned int);
/*------------------------------------------------------------------------------*/
/* Fonction d'allocation attachée à une structure de données : */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Alloc ( size_t Size, void ** Ptr, void * Data );
/*------------------------------------------------------------------------------*/
/* Fonction de désallocation attachée à une structure de données : */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_Free ( void * Ptr, void * Data );
/*------------------------------------------------------------------------------*/
/* Routine d'affichage d'un message d'erreur */
/*------------------------------------------------------------------------------*/
void DS_Error_Print ( void );
/*------------------------------------------------------------------------------*/
/* Pour préfixer les noms de heap avec l'identifiant de la librairie */
/*------------------------------------------------------------------------------*/
static char * DS_Name_Prefix (const char * Name);
/*------------------------------------------------------------------------------*/
/* Teste si une data structure a déjà été ouverte par le processus courant */
/*------------------------------------------------------------------------------*/
DST_Status DS_DataStruct_IsOpen (const char * DS_Name, NDT_Root ** Root);
/*------------------------------------------------------------------------------*/
/* Fonction manager de la liste des DS ouvertes */
/*------------------------------------------------------------------------------*/
NDT_Status DS_OpenedDS_List_Manager (va_list Args);

529
util/dsbench.c Normal file
View File

@ -0,0 +1,529 @@
#define DS_MODE 2
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/time.h>
#include <stdarg.h>
#include <node.h>
#include <datastr.h>
extern char * strdup ( const char *);
#define QUIT 0
#define CREATE_STRUCT 1
#define OPEN_STRUCT 2
#define CLOSE_STRUCT 3
#define DELETE_STRUCT 4
#define ADD_VALUE 5
#define REMOVE_VALUE 6
#define FIND_VALUE 7
#define CHG_LIST_TYPE 8
#define CONVERT_TO_TREE 9
#define CONVERT_TO_LIST 10
#define REORG 11
#define INFO 12
#define SHOW 13
#define CHECK 14
#define MANAGER_FILE_NAME "dsbench.so"
char DataStruct_Name [100];
char menu [1000];
char buf [100];
long int random ( void );
NDT_Status Module_Manager (va_list Args);
void init_menu ( NDT_Root *);
int print_menu ( NDT_Root *);
/* Mesure des temps d'exécution */
typedef struct {
double sec;
struct timeval start;
struct timeval stop;
} T_Cpt;
#define t_start(x) {gettimeofday (&(x.start), NULL);}
#define t_stop(x) {gettimeofday (&(x.stop), NULL); x.sec = (double)(x.stop.tv_sec) - (double)(x.start.tv_sec) + ((double)(x.stop.tv_usec) - (double)(x.start.tv_usec)) / 1000000;}
T_Cpt t_exec;
/* Définition des valeurs attachées aux noeuds de la structure */
typedef struct {
int Id;
char * Nom;
} T_Module;
int main (int argc, char ** argv)
{
NDT_Root * Root = NULL;
char * tmp;
int n, m, i, j;
int choice, Nb_Removed, Locked;
int Nb_Detected, Nb_Corrected;
T_Module * Module, Ref_Module;
NDT_Node * Node;
if (argc > 1 && !strcmp (argv[1], "-h"))
{
fprintf (stdout, "Usage : %s [-h] [instance [context]]\n", argv[0]);
return 0;
}
if (DS_Library_Open (0, NULL, DSD_DEBUG_ALL) != NDS_OK) return 0;
choice = print_menu (Root);
while (choice != QUIT)
{
switch (choice)
{
case CREATE_STRUCT:
fprintf (stdout, "\nNom de la structure à créer ? ");
gets (DataStruct_Name);
if (DS_DataStruct_Open (DataStruct_Name, &Root, NDD_DS_LIST | NDD_MN_FIFO, \
MANAGER_FILE_NAME, 0, DSD_CREATE, TRUE) != DSS_OK)
printf ("\nNOK\n");
else
{
strcpy (Root->Manager, "Module_Manager");
printf ("\nStructure créée : OK\n");
}
break;
case DELETE_STRUCT:
if (DS_DataStruct_Close (Root, DSD_DESTROY) == DSS_KO) printf ("\nNOK\n");
else
{
printf ("\nStructure détruite : OK\n");
Root = NULL;
}
break;
case OPEN_STRUCT:
fprintf (stdout, "\nNom de la structure à ouvrir ? ");
gets (DataStruct_Name);
if (DS_DataStruct_Open (DataStruct_Name, &Root, 0, NULL, 0, DSD_OPEN, TRUE) == NDS_KO)
printf ("\nNOK\n");
else
printf ("\nStructure ouverte : OK\n");
break;
case CLOSE_STRUCT:
if (DS_DataStruct_Close (Root, DSD_CLOSE) == DSS_KO) printf ("\nNOK\n");
else
{
printf ("\nStructure fermée : OK\n");
Root = NULL;
}
break;
case FIND_VALUE:
fprintf (stdout, "\nPlage de recherche (?->?) : ");
gets (buf);
tmp = strstr (buf, "->");
if (tmp != NULL)
{
* tmp = '\0';
n = atoi (buf);
tmp++;
tmp++;
m = atoi (tmp);
if (m < n)
{
printf ("\nEntrées non valides\n");
break;
}
}
else
{
printf ("\nEntrées non valides\n");
break;
}
DS_DataStruct_Lock (Root, DSD_READ, &Locked);
i = n;
j = m + 1;
t_start (t_exec);
while (i < j)
{
Module->Id = n + (random () % m);
DS_Node_Find (Root, &Node, Module, NULL);
i++;
}
t_stop (t_exec);
DS_DataStruct_Unlock (Root);
fprintf (stdout, "\n%d valeur(s) recherchée(s) en %.4f sec (%.2f select/sec)\n", \
m - n + 1, t_exec.sec, (m - n + 1) / t_exec.sec);
break;
case ADD_VALUE:
fprintf (stdout, "\nPlage des valeurs à ajouter (?->?) : ");
gets (buf);
tmp = strstr (buf, "->");
if (tmp != NULL)
{
* tmp = '\0';
n = atoi (buf);
tmp++;
tmp++;
m = atoi (tmp);
if (m < n)
{
printf ("\nEntrées non valides\n");
break;
}
}
else
{
printf ("\nEntrées non valides\n");
break;
}
DS_DataStruct_Lock (Root, DSD_WRITE, &Locked);
fprintf (stdout, "\nOrdre d'ajout (croissant=0 décroissant=1) ? ");
gets (buf);
choice = atoi (buf);
if (choice == 0)
{
i = n;
j = m + 1;
t_start (t_exec);
while (i < j)
{
if (DS_Value_Alloc (Root, (void **)&Module, "x", i) == NDS_OK) DS_Value_Add (Root, Module);
i++;
}
t_stop (t_exec);
}
else
{
i = m;
j = n - 1;
t_start (t_exec);
while (i > j)
{
if (DS_Value_Alloc (Root, (void **)&Module, "x", i) == NDS_OK) DS_Value_Add (Root, Module);
i--;
}
t_stop (t_exec);
}
DS_DataStruct_Unlock (Root);
fprintf (stdout, "\n%d valeur(s) ajoutée(s) en %.4f sec (%.2f ajouts/sec)\n", m - n + 1, \
t_exec.sec, (m - n + 1) / t_exec.sec);
break;
case REMOVE_VALUE:
Nb_Removed = 0;
fprintf (stdout, "\nPlage des valeurs à supprimer (?->?) : ");
gets (buf);
tmp = strstr (buf, "->");
if (tmp != NULL)
{
* tmp = '\0';
n = atoi (buf);
tmp++;
tmp++;
m = atoi (tmp);
if (m < n)
{
printf ("\nEntrées non valides\n");
break;
}
}
else
{
printf ("\nEntrées non valides\n");
break;
}
DS_DataStruct_Lock (Root, DSD_WRITE, &Locked);
fprintf (stdout, "\nOrdre de suppression (croissant=0 décroissant=1) ? ");
gets (buf);
choice = atoi (buf);
if (choice == 0)
{
i = n;
j = m + 1;
t_start (t_exec);
while (i < j)
{
Ref_Module.Id = i;
if (DS_Value_Remove (Root, &Ref_Module, (void **)&Module) == NDS_OK)
{
DS_Value_Free (Root, Module);
Nb_Removed++;
}
i++;
}
t_stop (t_exec);
}
else
{
i = m;
j = n - 1;
t_start (t_exec);
while (i > j)
{
Ref_Module.Id = i;
if (DS_Value_Remove (Root, &Ref_Module, (void **)&Module) == NDS_OK)
{
DS_Value_Free (Root, Module);
Nb_Removed++;
}
i--;
}
t_stop (t_exec);
}
DS_DataStruct_Unlock (Root);
fprintf (stdout, "\n%d valeur(s) supprimée(s) en %.4f sec (%.2f suppressions/sec)\n",\
Nb_Removed, t_exec.sec, (m - n + 1) / t_exec.sec);
break;
case CHG_LIST_TYPE:
fprintf (stdout, "\nType de liste (FIFO=0 ; FILO=1 ; triée=2) ? ");
gets (buf);
choice = atoi (buf);
DS_DataStruct_Lock (Root, DSD_WRITE, &Locked);
switch (choice)
{
case 0:
Root->Type = NDD_DS_LIST | NDD_MN_FIFO;
break;
case 1:
Root->Type = NDD_DS_LIST | NDD_MN_FILO;
break;
case 2:
Root->Type = NDD_DS_LIST | NDD_MN_ORDERED;
break;
default:
printf ("\nChoix non valide\n");
break;
}
DS_DataStruct_Unlock (Root);
break;
case REORG:
t_start (t_exec);
DS_DataStruct_Lock (Root, DSD_WRITE, &Locked);
DS_DataStruct_Reorg (Root);
DS_DataStruct_Unlock (Root);
t_stop (t_exec);
fprintf (stdout, "\nRéorganisation de la structure en %.4f sec\n", t_exec.sec);
break;
case CONVERT_TO_LIST:
t_start (t_exec);
DS_DataStruct_Lock (Root, DSD_WRITE, &Locked);
DS_DataStruct_Convert (Root, NDD_DS_LIST | NDD_MN_ORDERED);
DS_DataStruct_Unlock (Root);
t_stop (t_exec);
fprintf (stdout, "\nConversion arbre vers liste en %.4f sec\n", t_exec.sec);
break;
case CONVERT_TO_TREE:
t_start (t_exec);
DS_DataStruct_Lock (Root, DSD_WRITE, &Locked);
DS_DataStruct_Convert (Root, NDD_DS_TREE | NDD_MN_AUTO_EQU);
DS_DataStruct_Unlock (Root);
t_stop (t_exec);
fprintf (stdout, "\nConversion liste vers arbre en %.4f sec\n", t_exec.sec);
break;
case INFO:
DS_DataStruct_Lock (Root, DSD_READ, &Locked);
DS_DataStruct_Info_Print (Root, stdout);
DS_DataStruct_Unlock (Root);
break;
case SHOW:
DS_DataStruct_Lock (Root, DSD_READ, &Locked);
DS_DataStruct_Dump (Root, stdout);
DS_DataStruct_Unlock (Root);
break;
case CHECK:
Nb_Corrected = Nb_Detected = 0;
ND_DataStruct_Check (Root, &Nb_Detected, &Nb_Corrected, stderr);
break;
default:
fprintf (stdout, "\nChoix %d non défini\n", choice);
}
choice = print_menu (Root);
}
DS_Library_Close ();
return 0;
}
NDT_Status Module_Manager (va_list Args)
{
NDT_Command Command = (NDT_Command) va_arg (Args, NDT_Command);
if (Command == NDD_CMD_MAKE_VALUE)
{
NDT_Root * Root = va_arg (Args, NDT_Root *);
T_Module ** Module = va_arg (Args, T_Module **);
va_list Value_Args = va_arg (Args, va_list);
char * Nom = va_arg (Value_Args, char *);
int Id = va_arg (Value_Args, int);
if (DS_Alloc (Root, sizeof (T_Module) + strlen (Nom) + 1, (void **)Module) == DSS_OK)
{
(* Module)->Id = Id;
(* Module)->Nom = (char *)((size_t)(*Module) + sizeof (T_Module));
strcpy ((* Module)->Nom, Nom);
}
return (NDS_OK);
}
if (Command == NDD_CMD_PRINT_VALUE)
{
T_Module * Module = (T_Module *) va_arg (Args, void *);
FILE * Out = va_arg (Args, FILE *);
fprintf (Out, "Id Module=%d Nom Module='%s'", Module->Id, Module->Nom);
return (NDS_OK);
}
if (Command == NDD_CMD_DELETE_VALUE)
{
NDT_Root * Root = va_arg (Args, NDT_Root *);
T_Module * value = (T_Module *) va_arg (Args, void *);
DS_Free (Root, value);
return (NDS_OK);
}
if (Command == NDD_CMD_PRINT_INFO)
{
NDT_Root * Root = va_arg (Args, NDT_Root *);
FILE * Out = va_arg (Args, FILE *);
char * Root_Type;
DST_RootDesc * RootDesc;
switch ((int)(Root->Type & NDD_DS_MSK))
{
case NDD_DS_LIST :
switch ((int)(Root->Type & NDD_MN_MSK))
{
case NDD_MN_ORDERED : Root_Type = strdup ("liste triée"); break;
case NDD_MN_FILO : Root_Type = strdup ("liste FILO"); break;
case NDD_MN_FIFO : Root_Type = strdup ("liste FIFO"); break;
default: Root_Type = strdup ("inconnu"); break;
}
break;
case NDD_DS_TREE :
switch ((int)(Root->Type & NDD_MN_MSK))
{
case NDD_MN_AUTO_EQU : Root_Type = strdup ("arbre auto-équilibré"); break;
default: Root_Type = strdup ("arbre non auto-équilibré"); break;
}
break;
default: Root_Type = strdup ("inconnu"); break;
}
RootDesc = (DST_RootDesc *)(Root->User);
fprintf (Out, \
"\nStructure de type %s :\n\t- Nom = %s\n\t- Manager = %s\n\t- Nombre de modules = %ld\n", \
Root_Type, RootDesc->Heap_Name, RootDesc->Manager_FileName, Root->Node_Number);
if ((Root->Type & NDD_DS_MSK) == NDD_DS_TREE)
fprintf (Out, "\t- Profondeur maxi = %ld\n\t- Profondeur mini = %ld\n\t- Différence maximale autorisée = %ld\n\t- Nombre d'équilibrages = %ld\n", \
Root->Max_Depth, Root->Min_Depth, Root->Max_Dif, Root->Nb_Equ);
if (Root_Type) free (Root_Type);
return (NDS_OK);
}
if (Command == NDD_CMD_COMP_VALUE)
{
T_Module * Value1, * Value2;
long comp;
Value1 = (T_Module *) va_arg (Args, void *);
Value2 = (T_Module *) va_arg (Args, void *);
va_end (Args);
comp = Value1->Id - Value2->Id;
if (comp < 0) return NDS_LOWER;
if (comp > 0) return NDS_GREATER;
return NDS_EQUAL;
}
return (NDS_OK);
}
void init_menu ( NDT_Root * Root )
{
sprintf (menu, "Menu :\n");
sprintf (buf, " - %d) %-30s\n", QUIT, "Quitter");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s", CREATE_STRUCT, "Création de structure");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s\n", OPEN_STRUCT, "Ouverture de structure");
strcat (menu, buf);
if (Root != NULL)
{
sprintf (buf, " - %d) %-30s", CLOSE_STRUCT, "Fermer la structure");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s\n", DELETE_STRUCT, "Détruire la structure");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s", ADD_VALUE, "Ajout de valeurs");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s\n", REMOVE_VALUE, "Suppression de valeurs");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s\n", FIND_VALUE, "Recherche de valeurs aléatoires");
strcat (menu, buf);
if (ND_IS_LIST(Root))
{
sprintf (buf, " - %d) %-30s", CHG_LIST_TYPE, "Changement de type de liste");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s\n", CONVERT_TO_TREE, "Conversion en arbre");
strcat (menu, buf);
}
else
{
sprintf (buf, " - %d) %-30s", CONVERT_TO_LIST, "Conversion en liste triée");
strcat (menu, buf);
}
sprintf (buf, " - %d) %-30s\n", REORG, "Réorganisation");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s", INFO, "Informations sur la structure");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s\n", SHOW, "Affichage de la structure");
strcat (menu, buf);
sprintf (buf, " - %d) %-30s\n", CHECK, "Vérification de la structure");
strcat (menu, buf);
}
}
int print_menu ( NDT_Root * Root )
{
init_menu (Root);
fprintf (stdout, "\n---------------------------------------------------------\n");
fprintf (stdout, menu);
buf [0] = '\0';
while (buf [0] == '\0')
{
printf ("\nChoice ? ");
gets (buf);
}
return atoi (buf);
}

BIN
util/dsbench.xls Normal file
View File

Binary file not shown.

51
util/dsdump.c Normal file
View File

@ -0,0 +1,51 @@
#define SM_MODE 1
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdarg.h>
#include <node.h>
#include <shmem.h>
#include <datastr.h>
int main (int argc, char ** argv)
{
NDT_Node * Node;
SM_Library_Open (0, NULL, SMD_OPEN | SMD_DEBUG_ALL);
ND_Node_First_Get (SM_Base->MHR, &Node);
while (Node)
{
char * ptr;
SMT_MHH * MHH = ( SMT_MHH *)(Node->Value);
if ((ptr = strstr (MHH->Name, "DATASTR/")) != NULL)
{
int Locked;
SMT_Heap * Heap;
SMT_DSH * DSH;
NDT_Root * Root;
DST_RootDesc * RootDesc;
SM_Heap_Open (ptr, &Heap, 0, SMD_OPEN | SMD_READ, &Locked);
DSH = ( SMT_DSH *)(MHH->DSR->Head->Value);
Root = ( NDT_Root *)((size_t)(DSH->Start) + sizeof (NDT_Node) + sizeof (SMT_Chunk));
RootDesc = (DST_RootDesc *)(Root->User);
fprintf (stdout, "Data Structure \"%s\":\n\t- Manager = %s\n\t- Open semaphore = %d\n", ptr + strlen ("datastr/"), RootDesc->Manager_FileName, RootDesc->OpenSemID);
SM_Heap_Close (Heap);
}
ND_Node_Next_Get (Node, &Node);
}
SM_Library_Close (SMD_CLOSE);
return 0;
}