Main Page   Modules   Data Structures   File List   Data Fields   Globals  

lors_api.h

Go to the documentation of this file.
00001 #ifndef __LORSAPI_H__
00002 #define __LORSAPI_H__
00003 
00004 
00008 #ifdef HAVE_CONFIG_H
00009 #include <config.h>
00010 #endif
00011 
00012 #include <assert.h>
00013 #include <pthread.h>
00014 #include <semaphore.h>
00015 #include <sys/types.h>
00016 #include <jval.h>
00017 #include <jrb.h>
00018 #include <dllist.h>
00019 #include <ibp.h>
00020 
00021 #include <lors_error.h>
00022 #include <lors_opts.h>
00023 #include <lors_sem.h>
00024 
00025 #include <exnode.h>  
00026 #include <lbone_base.h>     /* added b/c ulong_t was suddenly undefined ... 1/27/04 */
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 typedef int64_t     longlong;
00033 
00034 #ifndef MIN
00035 #define MIN(x, y) (x < y ? x : y )
00036 #endif
00037 
00038 typedef struct __is_block
00039 {
00040     char       *buf;
00041     ulong_t     length;
00042     int         type;
00043     longlong    offset;
00044     LorsSem     *memory_count;
00045 } ISBlock;
00046 
00047 typedef struct __LorsBoundary
00048 {
00049     longlong            offset;
00050     longlong            length;
00051 } LorsBoundary;
00052 
00057 /*
00058  * @defgroup lors_api_IBP_storage_type  The LoRS API for IBP call
00059  */
00060 #define IBP_HARD               IBP_STABLE
00061 #define IBP_SOFT               IBP_VOLATILE
00062 
00066 struct __LorsExnode
00067 {
00068     /* this is a mapping from offsets to a Dllist of sets which contain
00069      * this offset. */
00070     JRB                 mapping_map;
00071     Exnode              *exnode;
00072     ExnodeMetadata     *md;
00073     longlong            seek_offset;
00074     longlong            alloc_length;
00075     longlong            logical_length;
00076 };
00077 typedef struct __LorsExnode LorsExnode;
00078 
00082 struct __lorsConditionStruct 
00083 {
00084     char        *function_name;
00085     ulong_t     blocksize;
00086     /* returns the outpu_length, the output data, and a new args_md
00087      * structure, composing all necessary information to decrypt it. */
00088     int        (*condition_data)(char              *input_buffer, 
00089                                  unsigned long int  input_length,
00090                                  unsigned long int  input_blocksize,
00091                                  char             **output_buffer, 
00092                                  unsigned long int *output_length, 
00093                                  unsigned long int *output_blocksize,
00094                                  ExnodeMetadata    *arguments);
00095     /* returns output, output_length, and accepts the previously created
00096      * lorsArg structure from deserialize or condition_data */
00097     int        (*uncondition_data)(char            *input_buffer, 
00098                                    unsigned long int  input_length,
00099                                    unsigned long int  input_blocksize,
00100                                    char             **output, 
00101                                    unsigned long int *out_length, 
00102                                    unsigned long int *output_blocksize,
00103                                    ExnodeMetadata *arguments);
00104     int              type;
00105     int              allocates;
00106     ExnodeMetadata   *arguments;
00107 };
00108 typedef struct __lorsConditionStruct LorsConditionStruct;
00109 
00113 struct __LorsSet
00114 {
00115     JRB                 mapping_map;
00116     pthread_mutex_t    *lock;
00117     longlong            curr_length;
00118     longlong            seek_offset;
00119 
00120     longlong            exnode_offset;
00121     longlong            max_length;
00122     Dllist              condition_list;
00123     ulong_t             data_blocksize;
00124     int                 copies;
00125 };
00126 typedef struct __LorsSet LorsSet;
00127 void lorsPrintSet(LorsSet *set);
00128 
00135 struct __LorsDepotPool
00136 {
00137     JRB                 list;   
00138     pthread_mutex_t    *lock;
00139     IBP_depot           lboneserver;
00140     int                 min_unique_depots;
00141     char               *location;
00142     ulong_t            size;
00143     int                 type;
00144     time_t              duration;
00145     int                 timeout;
00146 };
00147 typedef struct __LorsDepotPool LorsDepotPool;
00148 
00157 typedef struct __lbone_resolution
00158 {
00159     double ** resolution;
00160     int       src_cnt;
00161     int       dst_cnt;
00162     JRB       depotIndex;
00163 } LboneResolution;
00164 
00170 typedef struct __lbone_resoution_index
00171 {
00172     int       sourceIndex;
00173     int       destIndex;
00174 } LboneResolutionIndex;
00175 
00190 int lorsCreateResolutionFromFile(char *filename, 
00191                                  LboneResolution **lr, 
00192                                  int metric_index);
00208 int lorsCreateResolutionFromLBone(IBP_depot lboneserver,
00209                                   LboneResolution **lr,
00210                                   int opt);
00221 int lorsSetResolutionPoint(LboneResolution *lr, 
00222                            IBP_depot src, 
00223                            IBP_depot dst, 
00224                            double metric);
00234 int lorsGetResolutionPoint(LboneResolution *lr, 
00235                            IBP_depot src, 
00236                            IBP_depot dst, 
00237                            double *metric);
00247 int lorsSaveResolutionToFile(char *filename, LboneResolution *lr);
00248 
00268 int lorsUpdateDepotPoolFromResolution(LorsDepotPool *dp_src, LorsDepotPool *dp_dst, 
00269                                       LboneResolution *lr, int opts);
00270 
00279 int lorsFreeResolution(LboneResolution *lr);
00280 
00281 typedef Dllist LorsEnum;
00282 
00297 void lorsGetLibraryVersion(const char **package, const double *version);
00298 
00299 
00300 struct __depot_t
00301 {
00302     int                 id;
00303     IBP_depot           depot;
00304     LorsDepotPool       *dpp;
00305     pthread_mutex_t    *lock;
00306     double              score;      /* score */
00307     double              bandwidth;  /* bandwidth from local machine to this depot */
00308     double              proximity;  /* proximity to target position */
00309     int                 nfailure;   /* # of failures of this depot */
00310     int                 nthread;    /* # of threads using this depot */
00311     int                 nthread_done; /* # of threads finished using this depot */
00312     void               *tmp;
00313 };
00314 typedef struct __depot_t LorsDepot;
00315 
00316 
00317 typedef struct __lorsrsset LorsRSSet;
00318 
00319 struct __LorsMapping
00320 {
00321     /* PUBLIC READ/WRITE */
00322     ExnodeMetadata        *md;
00323     ExnodeFunction        *function;
00324     /* PUBLIC READ ONLY */
00325     longlong               exnode_offset;
00326 
00327     ulong_t                logical_length;
00328     ulong_t                logical_offset;
00329 
00330     ulong_t                alloc_length;   /* equivalent to 'maxSize' or physical size */
00331     ulong_t                alloc_offset;   /* offset within the ibp byte array */
00332 
00333     ulong_t                seek_offset;    /* equivalent to 'currSize' 
00334                                            or the amount written thus far. */
00335     struct   ibp_depot     depot;
00336     ulong_t                e2e_bs;         /* e2e block size */
00337     ulong_t                e2e_head_len;   /* e2e block header szie */
00338 
00339     /* PRIVATE */
00340     struct ibp_set_of_caps capset;
00341     struct ibp_capstatus   capstat;
00342 
00343     time_t                 begin_time;
00344     time_t                 timeout;
00345     int                    opts;
00346     LorsDepot             *lors_depot;
00347     LorsDepotPool         *dp;
00348     pthread_t              tid;
00349     pthread_attr_t         attr;
00350     pthread_mutex_t       *lock;
00351     ulong_t                   id;
00352     ulong_t                   i;
00353 
00354     int                     set_index;
00355     int                     coding_index;
00356     int                     n;
00357     int                     ft;
00358     ISBlock                 *block;
00359     LorsRSSet               *rss;
00360     int                     ret;
00361 };
00362 typedef struct __LorsMapping LorsMapping;
00363 
00375 int lorsSetEnum(LorsSet *set, LorsEnum *list);
00387 int lorsExnodeEnum(LorsExnode *exnode, LorsEnum   *list);
00388 
00399 int    lorsEnumNext (LorsEnum list, LorsEnum *iterator, LorsMapping **ret);
00410 int    lorsEnumFree (LorsEnum list);
00411 
00412 
00476 int    lorsGetDepotPool (LorsDepotPool  **dp,
00477                          char        *lbone_server,
00478                          int          lbone_server_port,
00479                          IBP_depot   *depots,
00480                          int          min_unique_depots,
00481                          char        *location,
00482                          ulong_t     storage_size,
00483                          int          storage_type,
00484                          time_t       duration,
00485                          int          nthreads,
00486                          int          timeout,
00487                          int          opts);
00488 
00513 int lorsUpdateDepotPool(LorsExnode *exnode,
00514                         LorsDepotPool **ret_dpp,
00515                         char       *lbone_server,
00516                         int         lbone_server_port,
00517                         char       *location,
00518                         int         nthreads,
00519                         int         timeout,
00520                         int         opts);
00521 
00531 int lorsFreeDepotPool(LorsDepotPool *dpp);
00532 /*-------------------------------------------------------------------------
00533  * Operations directly on LorsExnode 
00534  *-----------------------------------------------------------------------*/
00535 
00548 int    lorsExnodeCreate (LorsExnode ** exnode);
00549 int    lorsExnodeFree( LorsExnode *exnode);
00563 int    lorsAppendSet (LorsExnode * exnode,
00564                          LorsSet * set);
00565 
00578 int    lorsAppendMapping (LorsExnode * exnode,
00579                          LorsMapping * map);
00591 int    lorsDetachMapping (LorsExnode *exnode, LorsMapping *map);
00592 
00593 
00594 /*-------------------------------------------------------------------------
00595  * Wrapper Functions to the libexnode xml api
00596  *-----------------------------------------------------------------------*/
00597 
00613 int    lorsDeserialize (LorsExnode ** exnode,
00614                         char *buffer,
00615                         int  length,
00616                         char *schema);
00631 int    lorsFileDeserialize (LorsExnode ** exnode,
00632                             char *filename,
00633                             char *schema);
00634 
00653 int    lorsSerialize (LorsExnode * exnode,
00654                       char **buffer,
00655                       int readonly,
00656                       int *length);
00673 int    lorsFileSerialize (LorsExnode * exnode,
00674                           char *filename,
00675                           int readonly,
00676                           int opts);
00677 
00678 
00693 int lorsGetExnodeMetadata (LorsExnode *exnode, ExnodeMetadata **md);
00694 
00710 int lorsGetMappingMetadata (LorsMapping *map, ExnodeMetadata **md);
00711 int lorsMetadataMerge(ExnodeMetadata *src, ExnodeMetadata *dest);
00712 
00713 
00714 /*-------------------------------------------------------------------------
00715  * Primitive lorsSet* Functions
00716  *-----------------------------------------------------------------------*/
00732 int    lorsQuery (LorsExnode *exnode, 
00733                   LorsSet **set, 
00734                   longlong  offset, 
00735                   longlong  length,
00736                   int       opt); 
00737 
00738 #if 0
00739 
00755 int    lorsNameSet (LorsSet *set,
00756                     char *name);
00757 #endif
00758 
00768 int    lorsSetAddMapping (LorsSet *set, 
00769                          LorsMapping *map);
00770 
00779 int    lorsSetRemoveMapping (LorsSet *set, 
00780                          LorsMapping *map);
00781 
00782 /* 
00783  * Allocate the necessary IBP buffers and create the corresponding mappings
00784  * to fill the reqeusted number of copies and blocksize across 'length'.
00785  */
00805 int    lorsSetInit(LorsSet **set, 
00806                       ulong_t   data_blocksize,
00807                       int       copies,
00808                       int       opts);
00809 
00844 int    lorsSetStore (LorsSet        *set,
00845                      LorsDepotPool  *dp,
00846                      char           *buffer,
00847                      longlong        offset,
00848                      longlong        length,
00849                      LorsConditionStruct *lc,
00850                      int             nthreads,
00851                      int             timeout,
00852                      int             opts);
00853 
00854 /* 
00855  * this function is not valid for E2E encoded mappings.  Behavior is
00856  * unpredictable and will certainly fail if e2e mappings are given to it.
00857  *
00858  * set->data_blocksize must be a valid value.
00859  */
00860 int     lorsSetUpdate(LorsSet       *set, 
00861                   LorsDepotPool *dp, 
00862                   char *buffer, 
00863                   longlong offset, 
00864                   longlong length, 
00865                   int       nthreads,
00866                   int       timeout,
00867                   int       opts);
00909 long    lorsSetLoad (LorsSet     *set,
00910                     char        *buffer,
00911                     longlong     offset,
00912                     long         length,
00913                     ulong_t         block_size,
00914                     LorsConditionStruct *lc,
00915                     int          nthreads,
00916                     int          timeout,
00917                     int          opts);
00918 
00967 longlong    lorsSetRealTimeLoad (LorsSet * set,
00968                        char *buffer,
00969                        int  fd,
00970                        longlong offset,
00971                        longlong length,
00972                        ulong_t block_size,
00973                        int  pre_buf,
00974                        int  cache,
00975                        LorsConditionStruct *lc,
00976                        int nthreads,
00977                        int timeout,
00978                        int max_thds_per_depot,
00979                        int thds_per_job,
00980                        int progress_n,
00981                        int opts);
00982 
00983 
00984 
01016 int    lorsSetCopy (LorsSet      *srcSet,
01017                     LorsSet      *dstSet,
01018                     LorsDepotPool *dp,
01019                     LboneResolution    *lr,
01020                     longlong      offset,
01021                     longlong      length,
01022                     int           nthreads,
01023                     int           timeout,
01024                     int           opts);
01025 
01039 int    lorsSetMerge (LorsSet * src,
01040                      LorsSet * dest);
01041 
01073 int    lorsSetTrim (LorsSet * set,
01074                        longlong offset,
01075                        longlong length,
01076                        int nthreads,
01077                        int timeout,
01078                        int opts);
01079 #if 0
01080 
01101 int    lorsSetTrimMapping (LorsSet  *se, 
01102                               LorsMapping *map,
01103                               int  timeout,
01104                               int opts);
01105 #endif
01106 
01107 /*
01108  * extend or set the expiration times of those mappings contained within
01109  * offset-length.
01110  */
01144 int    lorsSetRefresh (LorsSet * set,
01145                        longlong offset,
01146                        longlong length,
01147                        time_t duration,
01148                        int nthreads,
01149                        int timeout,
01150                        int opts);
01151 
01178 int    lorsSetStat(LorsSet *set, 
01179                    int            nthreads,
01180                    int            timeout,
01181                    int            opts);
01182 
01195 int   lorsSetFree(LorsSet *set, int opts);
01196 
01212 int   lorsSetTrimCaps(LorsSet *set, int opts);
01213 
01214 #include <lors_util.h>
01215 #ifdef __cplusplus
01216 }
01217 #endif
01218 #endif