libshmem/include/shmem.h

/*---------------------------------------------------------------------------------*/
/* $RCSfile: shmem.h,v $							   */
/*---------------------------------------------------------------------------------*/
/* $Revision: 2.3 $								   */
/* $Name:  $							   */
/* $Date: 2005/06/26 23:07:40 $							   */
/* $Author: agibert $					       	           */
/*---------------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------------*/
/* This file is part of LibShMem                                                   */
/*                                                                                 */
/*    LibShMem is free software; you can redistribute it and/or modify             */
/*    it under the terms of the GNU Lesser General Public Licence as published by  */
/*    the Free Software Foundation; either version 2.1 of the License, or          */
/*    (at your option) any later version.                                          */
/*                                                                                 */
/*    LibShMem is distributed in the hope that it will be useful,                  */
/*    but WITHOUT ANY WARRANTY; without even the implied warranty of               */
/*    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                */
/*    GNU Lesser General Public License for more details.                          */
/*                                                                                 */
/*    You should have received a copy of the GNU Lesser General Public License     */
/*    along with LibShMem; if not, write to the Free Software                      */
/*    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA    */
/*---------------------------------------------------------------------------------*/





#ifndef _LIBSM
#define _LIBSM

#ifdef __cplusplus
extern "C" {
#endif

#include <stdarg.h>
#include <sys/types.h>
#include <node.h>

/* Code retour des fonctions constituant l'API */

    typedef long SMT_Status;

#define SMS_OK          NDS_OK      /* La fonction s'est correctement ex<65>cut<75>e et a produit un r<>sultat */
#define SMS_KO          NDS_KO      /* La fonction s'est correctement ex<65>cut<75>e mais n'a pas produit de r<>sultat */
#define SMS_NO_WAIT     2			/* Op<4F>ration sur s<>maphore en mode IPC_NOWAIT qui n'a pas pu aboutir */

#define SMS_YES         SMS_OK      /* R<>sultat bool<6F>en positif */
#define SMS_NO          SMS_KO      /* R<>sultat bool<6F>en n<>gatif */

#define SMS_ERRMEM      NDS_ERRMEM  /* Probl<62>me d'allocation m<>moire */
#define SMS_ERRAPI      NDS_ERRAPI  /* Utilisation incorrecte des API */
#define SMS_ERRSHM      -3          /* Probl<62>me relatif aux segments de m<>moire partag<61>e */
#define SMS_ERRSEM      -4          /* Probl<62>me relatif <20> l'utilisation des s<>maphores */
#define SMS_ERRSIG      -5          /* Op<4F>ration sur s<>maphore interrompue par un signal */

#define SM_ERROR(s)     ((s) < 0)     /* Tous les codes retour n<>gatifs correspondent <20> des erreurs */

    typedef int SMT_Flags;

#define SMD_UNDEF       0

/* Flags d'ouverture d'un heap ou d'une instance de la librairie */

#define SMD_CREATE      	0x01    /* Cr<43>ation */
#define SMD_OPEN        	0x02    /* Ouverture simple */
#define SMD_DESTROY     	0x04    /* Destruction */
#define SMD_CLOSE       	0x08    /* Fermeture simple */

/* NB : pour l'ouverture de la librairie, les valeurs SMD_OPEN et SMD_CREATE sont mutuellement exclusives */

/* Flags de verrouillage */

#define SMD_READ        	0x04    /* verrou partag<61> */
#define SMD_WRITE       	0x08    /* verrou exclusif */
#define SMD_NO_LOCK       	0x00    /* aucun verrou */

#define SMD_LOCK_MSK(a)   	((a) & (SMD_READ|SMD_WRITE))

/* Mode de debug sur l'ouverture de la librairie */

#define SMD_DEBUG_NONE  	0x00    /* pour n'afficher aucun message g<>n<EFBFBD>r<EFBFBD> par les diverses librairies */
#define SMD_DEBUG       	0x10    /* pour afficher les messages g<>n<EFBFBD>r<EFBFBD>s par la librairie */
#define SMD_DEBUG_ALL   	0x20    /* pour afficher les messages g<>n<EFBFBD>r<EFBFBD>s par toutes les librairies sous-jacentes */

#define SMD_DEBUG_MSK(a)    ((a) & (SMD_DEBUG|SMD_DEBUG_ALL))

/* Diff<66>rentes types de configuration d'un heap */

    typedef int SMT_Config;

#define SMD_SEGMENT_SIZE    	1	/* D<>finir la taille des segments */
#define SMD_HEAP_LIMIT      	2	/* D<>finir la taille maximale */
#define SMD_AUTO_COMPRESS      	3	/* D<>finir la taille d'un FCR <20> partir de laquelle
					   la compression du heap est autmatiquement activ<EFBFBD>e */

#define SMD_DEFAULT_COMPRESS    1000  /* si + de 1000 chunks libres, alors compression du heap */

/* Diff<66>rentes valeurs de configuration */

#define SMD_UNLIMITED           0
#define SMD_NO_AUTO_COMPRESS    0

/* Nom du heap syst<73>me */

#define HEAP_SYSTEM  "system"

#ifndef FALSE
#define FALSE 0
#endif

#ifndef TRUE
#define TRUE 1
#endif

    char SM_Error_Msg [512];

#ifndef SM_MODE
#define SM_MODE 0
#endif

#if SM_MODE == 1 /* API sans v<>rification des arguments */

#define SM_Library_Open             SM_Library_Open_I
#define SM_Library_Instance_Get     SM_Library_Instance_Get_I
#define SM_Library_Context_Set      SM_Library_Context_Set_I
#define SM_Library_Context_Get      SM_Library_Context_Get_I
#define SM_Library_Close            SM_Library_Close_I
#define SM_Library_Dump             SM_Library_Dump_I
#define SM_Library_Unlock           SM_Library_Unlock_I
#define SM_Library_Stderr_Set       SM_Library_Stderr_Set_I
#define SM_Heap_Exist               SM_Heap_Exist_I
#define SM_Heap_Open                SM_Heap_Open_I
#define SM_Heap_IsOpen              SM_Heap_IsOpen_I
#define SM_Heap_Close               SM_Heap_Close_I
#define SM_Heap_End                 SM_Heap_End_I
#define SM_Heap_Compress            SM_Heap_Compress_I
#define SM_Heap_Config              SM_Heap_Config_I
#define SM_Heap_Check               SM_Heap_Check_I
#define SM_Heap_Lock                SM_Heap_Lock_I
#define SM_Heap_Unlock              SM_Heap_Unlock_I
#define SM_Chunk_Alloc              SM_Chunk_Alloc_I
#define SM_Chunk_Free               SM_Chunk_Free_I

#else /* API avec v<>rification des arguments */

#define SM_Library_Open             SM_Library_Open_C
#define SM_Library_Instance_Get     SM_Library_Instance_Get_C
#define SM_Library_Context_Set      SM_Library_Context_Set_C
#define SM_Library_Context_Get      SM_Library_Context_Get_C
#define SM_Library_Close            SM_Library_Close_C
#define SM_Library_Dump             SM_Library_Dump_C
#define SM_Library_Unlock           SM_Library_Unlock_C
#define SM_Library_Stderr_Set       SM_Library_Stderr_Set_C
#define SM_Heap_Exist               SM_Heap_Exist_C
#define SM_Heap_Open                SM_Heap_Open_C
#define SM_Heap_IsOpen              SM_Heap_IsOpen_C
#define SM_Heap_Close               SM_Heap_Close_C
#define SM_Heap_End                 SM_Heap_End_C
#define SM_Heap_Compress            SM_Heap_Compress_C
#define SM_Heap_Config              SM_Heap_Config_C
#define SM_Heap_Check               SM_Heap_Check_C
#define SM_Heap_Lock                SM_Heap_Lock_C
#define SM_Heap_Unlock              SM_Heap_Unlock_C
#define SM_Chunk_Alloc              SM_Chunk_Alloc_C
#define SM_Chunk_Free               SM_Chunk_Free_C

#endif

/*------------------------------------------------------------------------------*/
/* Structure de la base de heaps                                                */
/*------------------------------------------------------------------------------*/

    typedef struct {
	    int         SysMemId;     /* Id de la 1<>re zone de m<>moire partag<61>e de la base */
	    int         DataMemId;    /* Id de la 2<>me zone de m<>moire partag<61>e de la base */
	    size_t      Size;         /* Taille de la zone de m<>moire partag<61>e */
	    int         SemId;        /* Id du s<>maphore pour la gestion des verrous */
	    NDT_Root *  MHR;          /* Memory Heap Root : racine de la liste de heap */
	    pid_t       Creator;      /* Id du processus cr<63>ateur de la base */
	    pid_t       Writer;       /* Id du dernier processus ayant acc<63>d<EFBFBD> en <20>criture <20> la base */
	    void *      Free;         /* Pointeur sur la premi<6D>re zone libre de la base */
	    void *      Attach;       /* Adresse du dernier attachement */
	    size_t      Segment_Size; /* Taille par d<>faut des segments qui composeront les heaps */
    } SMT_Base;

/* R<>f<EFBFBD>rence sur la base de heaps */

    SMT_Base * SM_Base;

/*------------------------------------------------------------------------------*/
/* Structure d'un MHH (Memory Heap Header)                                      */
/* Rappel : un MHH est une valeur attach<63>e <20> un MHN (Memory Heap Node)          */
/*------------------------------------------------------------------------------*/

    typedef struct {
	    char        Name [256];     /* Nom du heap */
	    int         SemId;          /* Id du s<>maphore pour la gestion des verrous */
	    NDT_Root *  DSR;            /* Data Segment Root */
	    NDT_Root *  ACR;            /* Allocated Chunks Root */
	    NDT_Root *  FCR;            /* Free Chunks Root */
	    pid_t       Writer;         /* Id du processus ayant acc<63>d<EFBFBD> en dernier au MHH en <20>criture */
	    int         State;          /* Etat d'un heap (valide, non valid<69> ou corrompu) */
	    size_t      Segment_Size;   /* Taille des segments de m<>moire composant le heap */
	    size_t      Limit_Size;     /* Taille limite du heap (par d<>faut : pas de limite) */
	    int         Auto_Compress;  /* Nombre de chunks libres <20> partir duquel le heap est automatiquement compress<73> */
	    long        Compress_Nb;    /* Nomber of time the heap has been compressed */
    } SMT_MHH;

/* Heap ouvert */

    typedef struct {
	    char    *   Name;
	    SMT_MHH *   MHH;
	    SMT_Flags   Lock_Mode;  /* Mode dans lequel le heap est verrouill<6C> */
	    int         Nb_Seg;     /* Nombre de segments du heap lors de son ouverture */
    } SMT_Heap;

/*------------------------------------------------------------------------------*/
/* Structure d'un DSH (Data Segment Header)                                     */
/* Rappel : un DSH est une valeur attach<63>e <20> un DSN (noeud de DSR)              */
/*------------------------------------------------------------------------------*/

    typedef struct {
	    int         MemId;      /* Id de la zone de m<>moire partag<61>e */
	    size_t      Size;       /* Taille de la zone de m<>moire partag<61>e */
	    void *      Start;      /* Adresse de d<>but de la zone de m<>moire partag<61>e */
    } SMT_DSH;

/*------------------------------------------------------------------------------*/
/* Structure d'un chunk                                                         */
/* Rappel : un chunk est la valeur attach<63>e <20> un noeud de ACR ou FCR            */
/*------------------------------------------------------------------------------*/

    typedef struct {
	    size_t      Size;       /* Taille allou<6F>e au chunk */
	    void *      Data;       /* Adresse de la zone de donn<6E>es du chunk */
    } SMT_Chunk;

/*------------------------------------------------------------------------------*/
/* Ouverture d'une instance de la librairie                                     */
/*------------------------------------------------------------------------------*/
/* (I) Instance : num<75>ro d'instance de la librairie                             */
/* (I) Context  : nom du nouveau contexte                                       */
/* (I) Flags    : indicateur cr<63>ation/ouverture + mode d'affichage des erreurs  */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Open_I ( int Instance, const char * Context, SMT_Flags Flags );
    SMT_Status SM_Library_Open_C ( int Instance, const char * Context, SMT_Flags Flags );

/*------------------------------------------------------------------------------*/
/* R<>cup<75>ration du num<75>ro de l'instance utilis<69>e                                */
/*------------------------------------------------------------------------------*/
/* (O) Instance : adresse du num<75>ro de l'instance utilis<69>e                      */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Instance_Get_I ( int * Instance);
    SMT_Status SM_Library_Instance_Get_C ( int * Instance);

/*------------------------------------------------------------------------------*/
/* Changement de contexte d'utilisation de la librairie                         */
/*------------------------------------------------------------------------------*/
/* (I) Context : nom du nouveau contexte                                        */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Context_Set_I ( const char * Context );
    SMT_Status SM_Library_Context_Set_C ( const char * Context );

/*------------------------------------------------------------------------------*/
/* R<>cup<75>ration du nom du contexte utilis<69>                                      */
/*------------------------------------------------------------------------------*/
/* (O) Context : adresse du nom du contexte utilis<69>                             */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Context_Get_I ( char ** Context );
    SMT_Status SM_Library_Context_Get_C ( char ** Context );

/*------------------------------------------------------------------------------*/
/* Fermeture de l'instance de la librairie                                      */
/*------------------------------------------------------------------------------*/
/* (I) Flags : mode de fermeture (destruction ou fermeture simple)              */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Close_I ( SMT_Flags Flags );
    SMT_Status SM_Library_Close_C ( SMT_Flags Flags );

/*------------------------------------------------------------------------------*/
/*  Affichage des informations de la base de m<>moires partag<61>es                 */
/*------------------------------------------------------------------------------*/
/* (I) Out : pointeur sur le flux de sortie                                     */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Dump_I ( FILE * Out );
    SMT_Status SM_Library_Dump_C ( FILE * Out );

/*------------------------------------------------------------------------------*/
/*  Lib<69>ration de tous les verrous (base, heap)                                 */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Unlock_I ( void );
    SMT_Status SM_Library_Unlock_C ( void );

/*------------------------------------------------------------------------------*/
/* D<>finition de la sortie standard des messages d'erreur de la librairie       */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Library_Stderr_Set_I ( FILE * Out );
    SMT_Status SM_Library_Stderr_Set_C ( FILE * Out );

/*------------------------------------------------------------------------------*/
/* Test d'existence d'un heap                                                   */
/*------------------------------------------------------------------------------*/
/* (I) Heap_Name    : nom du heap                                               */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Exist_I ( const char * Heap_Name );
    SMT_Status SM_Heap_Exist_C ( const char * Heap_Name );

/*------------------------------------------------------------------------------*/
/* Ouverture/cr<63>ation d'un heap                                                 */
/*------------------------------------------------------------------------------*/
/* (I) Heap_Name : nom du heap                                                  */
/* (O) Heap      : pointeur sur le heap ouvert / cr<63><72>                           */
/* (I) Seg_Size  : taille des segments du heap                                  */
/* (I) Flags     : mode d'ouverture du heap                                     */
/* (O) Locked    : verrou effectif (TRUE ou FALSE)                              */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Open_I ( const char * Heap_Name, SMT_Heap ** Heap, size_t Seg_Size, SMT_Flags Flags, int * Locked );
    SMT_Status SM_Heap_Open_C ( const char * Heap_Name, SMT_Heap ** Heap, size_t Seg_Size, SMT_Flags Flags, int * Locked );

/*------------------------------------------------------------------------------*/
/* Teste si un heap a d<>j<EFBFBD> <20>t<EFBFBD> ouvert par le processus courant                  */
/*------------------------------------------------------------------------------*/
/* (I) Heap_Name : nom du heap                                                  */
/* (O) Heap      : adresse du pointeur sur le heap ouvert                       */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_IsOpen_I ( const char * Heap_Name, SMT_Heap ** Heap );
    SMT_Status SM_Heap_IsOpen_C ( const char * Heap_Name, SMT_Heap ** Heap );

/*------------------------------------------------------------------------------*/
/* Fermeture d'un heap                                                          */
/*------------------------------------------------------------------------------*/
/* (I) Heap   : pointeur sur un heap ouvert                                     */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Close_I ( SMT_Heap * Heap );
    SMT_Status SM_Heap_Close_C ( SMT_Heap * Heap );

/*------------------------------------------------------------------------------*/
/* Destruction d'un heap                                                        */
/*------------------------------------------------------------------------------*/
/* (I) Heap_Name    : nom du heap                                               */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_End_I ( const char * Heap_Name );
    SMT_Status SM_Heap_End_C ( const char * Heap_Name );

/*------------------------------------------------------------------------------*/
/* Compression d'un heap                                                        */
/*------------------------------------------------------------------------------*/
/* (I) Heap     : pointeur sur un heap ouvert                                   */
/* (O) Compress : pointeur sur la taille m<>moire gagn<67>e                         */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Compress_I ( SMT_Heap * Heap, size_t * Compress );
    SMT_Status SM_Heap_Compress_C ( SMT_Heap * Heap, size_t * Compress );

/*------------------------------------------------------------------------------*/
/* Configuration d'un heap                                                      */
/*------------------------------------------------------------------------------*/
/* (I) Heap  : pointeur sur un heap ouvert                                      */
/* (I) Tag   : type de configuration                                            */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Config_I ( SMT_Heap * Heap, SMT_Config Tag, ... );
    SMT_Status SM_Heap_Config_C ( SMT_Heap * Heap, SMT_Config Tag, ... );

/*------------------------------------------------------------------------------*/
/* V<>rification/correction des structures d'un heap :                           */
/*------------------------------------------------------------------------------*/
/* (I) Heap         : pointeur sur un heap ouvert                               */
/* (O) Nb_Detected  : pointeur sur le nombre d'erreurs d<>tect<63>es                */
/* (O) Nb_Corrected : pointeur sur le nombre d'erreurs corrig<69>es                */
/* (I) Out          : pointeur sur le flux de sortie du rapport                 */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Check_I ( SMT_Heap * Heap, int * Nb_Detected, int * Nb_Corrected, FILE * Out);
    SMT_Status SM_Heap_Check_C ( SMT_Heap * Heap, int * Nb_Detected, int * Nb_Corrected, FILE * Out);

/*------------------------------------------------------------------------------*/
/* Pose d'un verrou sur un heap                                                 */
/*------------------------------------------------------------------------------*/
/* (I) Heap      : pointeur sur un heap ouvert                                  */
/* (I) Flags     : mode de verrouillage (SMD_READ ou SMD_WRITE)                 */
/* (O) Locked    : verrouillage effectu<74> (TRUE ou FALSE)                        */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Lock_I ( SMT_Heap * Heap, SMT_Flags Flags, int * Locked );
    SMT_Status SM_Heap_Lock_C ( SMT_Heap * Heap, SMT_Flags Flags, int * Locked );

/*------------------------------------------------------------------------------*/
/* Lib<69>ration d'un verrou sur un heap                                           */
/*------------------------------------------------------------------------------*/
/* (I) Heap   : pointeur sur un heap ouvert                                     */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Heap_Unlock_I ( SMT_Heap * Heap );
    SMT_Status SM_Heap_Unlock_C ( SMT_Heap * Heap );

/*------------------------------------------------------------------------------*/
/* Allocation d'un chunk dans un heap                                           */
/*------------------------------------------------------------------------------*/
/* (I) Heap      : pointeur sur un heap ouvert                                  */
/* (I) Size      : taille du chunk                                              */
/* (O) Ptr       : pointeur sur la zone de donn<6E>es allou<6F>e                      */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Chunk_Alloc_I ( SMT_Heap * Heap, size_t Alloc_Size, void ** Ptr );
    SMT_Status SM_Chunk_Alloc_C ( SMT_Heap * Heap, size_t Alloc_Size, void ** Ptr );

/*------------------------------------------------------------------------------*/
/* D<>sallocation d'un chunk                                                     */
/*------------------------------------------------------------------------------*/
/* (I) Heap   : pointeur sur un heap ouvert                                     */
/* (I) Ptr    : adresse de la zone de donn<6E>es du chunk <20> d<>sallouer             */
/*------------------------------------------------------------------------------*/
    SMT_Status SM_Chunk_Free_I ( SMT_Heap * Heap, void * Ptr );
    SMT_Status SM_Chunk_Free_C ( SMT_Heap * Heap, void * Ptr );

#ifdef __cplusplus
}
#endif

#endif