subversion/libsvn_fs/fs-loader.h

   1 /*
   2  * fs_loader.h:  Declarations for the FS loader library
   3  *
   4  * ====================================================================
   5  * Copyright (c) 2000-2008 CollabNet.  All rights reserved.
   6  *
   7  * This software is licensed as described in the file COPYING, which
   8  * you should have received as part of this distribution.  The terms
   9  * are also available at http://subversion.tigris.org/license-1.html.
  10  * If newer versions of this license are posted there, you may use a
  11  * newer version instead, at your option.
  12  *
  13  * This software consists of voluntary contributions made by many
  14  * individuals.  For exact contribution history, see the revision
  15  * history and logs, available at http://subversion.tigris.org/.
  16  * ====================================================================
  17  */
  18 \f
  19
  20 #ifndef LIBSVN_FS_FS_H
  21 #define LIBSVN_FS_FS_H
  22
  23 #include "svn_version.h"
  24 #include "svn_fs.h"
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif /* __cplusplus */
  29
  30 \f
  31 /* The FS loader library implements the a front end to "filesystem
  32    abstract providers" (FSAPs), which implement the svn_fs API.
  33
  34    The loader library divides up the FS API into five categories:
  35
  36      - Top-level functions, which operate on paths to an FS
  37      - Functions which operate on an FS object
  38      - Functions which operate on a transaction object
  39      - Functions which operate on a root object
  40      - Functions which operate on a history object
  41
  42    Some generic fields of the FS, transaction, root, and history
  43    objects are defined by the loader library; the rest are stored in
  44    the "fsap_data" field which is defined by the FSAP.  Likewise, some
  45    of the very simple svn_fs API functions (such as svn_fs_root_fs)
  46    are defined by the loader library, while the rest are implemented
  47    through vtable calls defined by the FSAP.
  48
  49    If you are considering writing a new database-backed filesystem
  50    implementation, it may be appropriate to add a second, lower-level
  51    abstraction to the libsvn_fs_base library which currently
  52    implements the BDB filesystem type.  Consult the dev list for
  53    details on the "FSP-level" abstraction concept.
  54 */
  55
  56
  57 \f
  58 /*** Top-level library vtable type ***/
  59
  60 typedef struct fs_library_vtable_t
  61 {
  62   /* This field should always remain first in the vtable.
  63      Apart from that, it can be changed however you like, since exact
  64      version equality is required between loader and module.  This policy
  65      was weaker during 1.1.x, but only in ways which do not conflict with
  66      this statement, now that the minor version has increased. */
  67   const svn_version_t *(*get_version)(void);
  68
  69   /* The open_fs/create/open_fs_for_recovery/upgrade_fs functions are
  70      serialized so that they may use the common_pool parameter to
  71      allocate fs-global objects such as the bdb env cache. */
  72   svn_error_t *(*create)(svn_fs_t *fs, const char *path, apr_pool_t *pool,
  73                          apr_pool_t *common_pool);
  74   svn_error_t *(*open_fs)(svn_fs_t *fs, const char *path, apr_pool_t *pool,
  75                           apr_pool_t *common_pool);
  76   /* open_for_recovery() is like open(), but used to fill in an fs pointer
  77      that will be passed to recover().  We assume that the open() method
  78      might not be immediately appropriate for recovery. */
  79   svn_error_t *(*open_fs_for_recovery)(svn_fs_t *fs, const char *path,
  80                                        apr_pool_t *pool,
  81                                        apr_pool_t *common_pool);
  82   svn_error_t *(*upgrade_fs)(svn_fs_t *fs, const char *path, apr_pool_t *pool,
  83                              apr_pool_t *common_pool);
  84   svn_error_t *(*delete_fs)(const char *path, apr_pool_t *pool);
  85   svn_error_t *(*hotcopy)(const char *src_path, const char *dest_path,
  86                           svn_boolean_t clean, apr_pool_t *pool);
  87   const char *(*get_description)(void);
  88   svn_error_t *(*recover)(svn_fs_t *fs,
  89                           svn_cancel_func_t cancel_func, void *cancel_baton,
  90                           apr_pool_t *pool);
  91
  92   /* Provider-specific functions should go here, even if they could go
  93      in an object vtable, so that they are all kept together. */
  94   svn_error_t *(*bdb_logfiles)(apr_array_header_t **logfiles,
  95                                const char *path, svn_boolean_t only_unused,
  96                                apr_pool_t *pool);
  97
  98   /* This is to let the base provider implement the deprecated
  99      svn_fs_parse_id, which we've decided doesn't belong in the FS
 100      API.  If we change our minds and decide to add a real
 101      svn_fs_parse_id variant which takes an FS object, it should go
 102      into the FS vtable. */
 103   svn_fs_id_t *(*parse_id)(const char *data, apr_size_t len,
 104                            apr_pool_t *pool);
 105 } fs_library_vtable_t;
 106
 107 /* This is the type of symbol an FS module defines to fetch the
 108    library vtable. The LOADER_VERSION parameter must remain first in
 109    the list, and the function must use the C calling convention on all
 110    platforms, so that the init functions can safely read the version
 111    parameter.  The COMMON_POOL parameter must be a pool with a greater
 112    lifetime than the fs module so that fs global state can be kept
 113    in it and cleaned up on termination before the fs module is unloaded.
 114    Calls to these functions are globally serialized so that they have
 115    exclusive access to the COMMON_POOL parameter.
 116
 117    ### need to force this to be __cdecl on Windows... how?? */
 118 typedef svn_error_t *(*fs_init_func_t)(const svn_version_t *loader_version,
 119                                        fs_library_vtable_t **vtable,
 120                                        apr_pool_t* common_pool);
 121
 122 /* Here are the declarations for the FS module init functions.  If we
 123    are using DSO loading, they won't actually be linked into
 124    libsvn_fs.  Note that these private functions have a common_pool
 125    parameter that may be used for fs module scoped variables such as
 126    the bdb cache.  This will be the same common_pool that is passed
 127    to the create and open functions and these init functions (as well
 128    as the open and create functions) are globally serialized so that
 129    they have exclusive access to the common_pool. */
 130 svn_error_t *svn_fs_base__init(const svn_version_t *loader_version,
 131                                fs_library_vtable_t **vtable,
 132                                apr_pool_t* common_pool);
 133 svn_error_t *svn_fs_fs__init(const svn_version_t *loader_version,
 134                              fs_library_vtable_t **vtable,
 135                              apr_pool_t* common_pool);
 136
 137
 138 \f
 139 /*** vtable types for the abstract FS objects ***/
 140
 141 typedef struct fs_vtable_t
 142 {
 143   svn_error_t *(*youngest_rev)(svn_revnum_t *youngest_p, svn_fs_t *fs,
 144                                apr_pool_t *pool);
 145   svn_error_t *(*revision_prop)(svn_string_t **value_p, svn_fs_t *fs,
 146                                 svn_revnum_t rev, const char *propname,
 147                                 apr_pool_t *pool);
 148   svn_error_t *(*revision_proplist)(apr_hash_t **table_p, svn_fs_t *fs,
 149                                     svn_revnum_t rev, apr_pool_t *pool);
 150   svn_error_t *(*change_rev_prop)(svn_fs_t *fs, svn_revnum_t rev,
 151                                   const char *name,
 152                                   const svn_string_t *value,
 153                                   apr_pool_t *pool);
 154   svn_error_t *(*get_uuid)(svn_fs_t *fs, const char **uuid, apr_pool_t *pool);
 155   svn_error_t *(*set_uuid)(svn_fs_t *fs, const char *uuid, apr_pool_t *pool);
 156   svn_error_t *(*revision_root)(svn_fs_root_t **root_p, svn_fs_t *fs,
 157                                 svn_revnum_t rev, apr_pool_t *pool);
 158   svn_error_t *(*begin_txn)(svn_fs_txn_t **txn_p, svn_fs_t *fs,
 159                             svn_revnum_t rev, apr_uint32_t flags,
 160                             apr_pool_t *pool);
 161   svn_error_t *(*open_txn)(svn_fs_txn_t **txn, svn_fs_t *fs,
 162                            const char *name, apr_pool_t *pool);
 163   svn_error_t *(*purge_txn)(svn_fs_t *fs, const char *txn_id,
 164                             apr_pool_t *pool);
 165   svn_error_t *(*list_transactions)(apr_array_header_t **names_p,
 166                                     svn_fs_t *fs, apr_pool_t *pool);
 167   svn_error_t *(*deltify)(svn_fs_t *fs, svn_revnum_t rev, apr_pool_t *pool);
 168   svn_error_t *(*lock)(svn_lock_t **lock, svn_fs_t *fs,
 169                        const char *path, const char *token,
 170                        const char *comment, svn_boolean_t is_dav_comment,
 171                        apr_time_t expiration_date,
 172                        svn_revnum_t current_rev, svn_boolean_t steal_lock,
 173                        apr_pool_t *pool);
 174   svn_error_t *(*generate_lock_token)(const char **token, svn_fs_t *fs,
 175                                       apr_pool_t *pool);
 176   svn_error_t *(*unlock)(svn_fs_t *fs, const char *path, const char *token,
 177                          svn_boolean_t break_lock, apr_pool_t *pool);
 178   svn_error_t *(*get_lock)(svn_lock_t **lock, svn_fs_t *fs,
 179                            const char *path, apr_pool_t *pool);
 180   svn_error_t *(*get_locks)(svn_fs_t *fs, const char *path,
 181                             svn_fs_get_locks_callback_t get_locks_func,
 182                             void *get_locks_baton,
 183                             apr_pool_t *pool);
 184   svn_error_t *(*bdb_set_errcall)(svn_fs_t *fs,
 185                                   void (*handler)(const char *errpfx,
 186                                                   char *msg));
 187 } fs_vtable_t;
 188
 189
 190 typedef struct txn_vtable_t
 191 {
 192   svn_error_t *(*commit)(const char **conflict_p, svn_revnum_t *new_rev,
 193                          svn_fs_txn_t *txn, apr_pool_t *pool);
 194   svn_error_t *(*abort)(svn_fs_txn_t *txn, apr_pool_t *pool);
 195   svn_error_t *(*get_prop)(svn_string_t **value_p, svn_fs_txn_t *txn,
 196                            const char *propname, apr_pool_t *pool);
 197   svn_error_t *(*get_proplist)(apr_hash_t **table_p, svn_fs_txn_t *txn,
 198                                apr_pool_t *pool);
 199   svn_error_t *(*change_prop)(svn_fs_txn_t *txn, const char *name,
 200                               const svn_string_t *value, apr_pool_t *pool);
 201   svn_error_t *(*root)(svn_fs_root_t **root_p, svn_fs_txn_t *txn,
 202                        apr_pool_t *pool);
 203   svn_error_t *(*change_props)(svn_fs_txn_t *txn, apr_array_header_t *props,
 204                                apr_pool_t *pool);
 205 } txn_vtable_t;
 206
 207
 208 /* Some of these operations accept multiple root arguments.  Since the
 209    roots may not all have the same vtable, we need a rule to determine
 210    which root's vtable is used.  The rule is: if one of the roots is
 211    named "target", we use that root's vtable; otherwise, we use the
 212    first root argument's vtable. */
 213 typedef struct root_vtable_t
 214 {
 215   /* Determining what has changed in a root */
 216   svn_error_t *(*paths_changed)(apr_hash_t **changed_paths_p,
 217                                 svn_fs_root_t *root,
 218                                 apr_pool_t *pool);
 219
 220   /* Generic node operations */
 221   svn_error_t *(*check_path)(svn_node_kind_t *kind_p, svn_fs_root_t *root,
 222                              const char *path, apr_pool_t *pool);
 223   svn_error_t *(*node_history)(svn_fs_history_t **history_p,
 224                                svn_fs_root_t *root, const char *path,
 225                                apr_pool_t *pool);
 226   svn_error_t *(*node_id)(const svn_fs_id_t **id_p, svn_fs_root_t *root,
 227                           const char *path, apr_pool_t *pool);
 228   svn_error_t *(*node_created_rev)(svn_revnum_t *revision,
 229                                    svn_fs_root_t *root, const char *path,
 230                                    apr_pool_t *pool);
 231   svn_error_t *(*node_origin_rev)(svn_revnum_t *revision,
 232                                   svn_fs_root_t *root, const char *path,
 233                                   apr_pool_t *pool);
 234   svn_error_t *(*node_created_path)(const char **created_path,
 235                                     svn_fs_root_t *root, const char *path,
 236                                     apr_pool_t *pool);
 237   svn_error_t *(*delete_node)(svn_fs_root_t *root, const char *path,
 238                               apr_pool_t *pool);
 239   svn_error_t *(*copied_from)(svn_revnum_t *rev_p, const char **path_p,
 240                               svn_fs_root_t *root, const char *path,
 241                               apr_pool_t *pool);
 242   svn_error_t *(*closest_copy)(svn_fs_root_t **root_p, const char **path_p,
 243                                svn_fs_root_t *root, const char *path,
 244                                apr_pool_t *pool);
 245
 246   /* Property operations */
 247   svn_error_t *(*node_prop)(svn_string_t **value_p, svn_fs_root_t *root,
 248                             const char *path, const char *propname,
 249                             apr_pool_t *pool);
 250   svn_error_t *(*node_proplist)(apr_hash_t **table_p, svn_fs_root_t *root,
 251                                 const char *path, apr_pool_t *pool);
 252   svn_error_t *(*change_node_prop)(svn_fs_root_t *root, const char *path,
 253                                    const char *name,
 254                                    const svn_string_t *value,
 255                                    apr_pool_t *pool);
 256   svn_error_t *(*props_changed)(int *changed_p, svn_fs_root_t *root1,
 257                                 const char *path1, svn_fs_root_t *root2,
 258                                 const char *path2, apr_pool_t *pool);
 259
 260   /* Directories */
 261   svn_error_t *(*dir_entries)(apr_hash_t **entries_p, svn_fs_root_t *root,
 262                               const char *path, apr_pool_t *pool);
 263   svn_error_t *(*make_dir)(svn_fs_root_t *root, const char *path,
 264                            apr_pool_t *pool);
 265   svn_error_t *(*copy)(svn_fs_root_t *from_root, const char *from_path,
 266                        svn_fs_root_t *to_root, const char *to_path,
 267                        apr_pool_t *pool);
 268   svn_error_t *(*revision_link)(svn_fs_root_t *from_root,
 269                                 svn_fs_root_t *to_root,
 270                                 const char *path,
 271                                 apr_pool_t *pool);
 272
 273   /* Files */
 274   svn_error_t *(*file_length)(svn_filesize_t *length_p, svn_fs_root_t *root,
 275                               const char *path, apr_pool_t *pool);
 276   svn_error_t *(*file_md5_checksum)(unsigned char digest[],
 277                                     svn_fs_root_t *root,
 278                                     const char *path, apr_pool_t *pool);
 279   svn_error_t *(*file_contents)(svn_stream_t **contents,
 280                                 svn_fs_root_t *root, const char *path,
 281                                 apr_pool_t *pool);
 282   svn_error_t *(*make_file)(svn_fs_root_t *root, const char *path,
 283                             apr_pool_t *pool);
 284   svn_error_t *(*apply_textdelta)(svn_txdelta_window_handler_t *contents_p,
 285                                   void **contents_baton_p,
 286                                   svn_fs_root_t *root, const char *path,
 287                                   const char *base_checksum,
 288                                   const char *result_checksum,
 289                                   apr_pool_t *pool);
 290   svn_error_t *(*apply_text)(svn_stream_t **contents_p, svn_fs_root_t *root,
 291                              const char *path, const char *result_checksum,
 292                              apr_pool_t *pool);
 293   svn_error_t *(*contents_changed)(int *changed_p, svn_fs_root_t *root1,
 294                                    const char *path1, svn_fs_root_t *root2,
 295                                    const char *path2, apr_pool_t *pool);
 296   svn_error_t *(*get_file_delta_stream)(svn_txdelta_stream_t **stream_p,
 297                                         svn_fs_root_t *source_root,
 298                                         const char *source_path,
 299                                         svn_fs_root_t *target_root,
 300                                         const char *target_path,
 301                                         apr_pool_t *pool);
 302
 303   /* Merging. */
 304   svn_error_t *(*merge)(const char **conflict_p,
 305                         svn_fs_root_t *source_root,
 306                         const char *source_path,
 307                         svn_fs_root_t *target_root,
 308                         const char *target_path,
 309                         svn_fs_root_t *ancestor_root,
 310                         const char *ancestor_path,
 311                         apr_pool_t *pool);
 312   svn_error_t *(*get_mergeinfo)(svn_mergeinfo_catalog_t *catalog,
 313                                 svn_fs_root_t *root,
 314                                 const apr_array_header_t *paths,
 315                                 svn_mergeinfo_inheritance_t inherit,
 316                                 svn_boolean_t include_descendants,
 317                                 apr_pool_t *pool);
 318 } root_vtable_t;
 319
 320
 321 typedef struct history_vtable_t
 322 {
 323   svn_error_t *(*prev)(svn_fs_history_t **prev_history_p,
 324                        svn_fs_history_t *history, svn_boolean_t cross_copies,
 325                        apr_pool_t *pool);
 326   svn_error_t *(*location)(const char **path, svn_revnum_t *revision,
 327                            svn_fs_history_t *history, apr_pool_t *pool);
 328 } history_vtable_t;
 329
 330
 331 typedef struct id_vtable_t
 332 {
 333   svn_string_t *(*unparse)(const svn_fs_id_t *id, apr_pool_t *pool);
 334   int (*compare)(const svn_fs_id_t *a, const svn_fs_id_t *b);
 335 } id_vtable_t;
 336
 337
 338 \f
 339 /*** Definitions of the abstract FS object types ***/
 340
 341 /* These are transaction properties that correspond to the bitfields
 342    in the 'flags' argument to svn_fs_lock().  */
 343 #define SVN_FS__PROP_TXN_CHECK_LOCKS           SVN_PROP_PREFIX "check-locks"
 344 #define SVN_FS__PROP_TXN_CHECK_OOD             SVN_PROP_PREFIX "check-ood"
 345
 346 struct svn_fs_t
 347 {
 348   /* The pool in which this fs object is allocated */
 349   apr_pool_t *pool;
 350
 351   /* The path to the repository's top-level directory */
 352   char *path;
 353
 354   /* A callback for printing warning messages */
 355   svn_fs_warning_callback_t warning;
 356   void *warning_baton;
 357
 358   /* The filesystem configuration */
 359   apr_hash_t *config;
 360
 361   /* An access context indicating who's using the fs */
 362   svn_fs_access_t *access_ctx;
 363
 364   /* FSAP-specific vtable and private data */
 365   fs_vtable_t *vtable;
 366   void *fsap_data;
 367 };
 368
 369
 370 struct svn_fs_txn_t
 371 {
 372   /* The filesystem to which this transaction belongs */
 373   svn_fs_t *fs;
 374
 375   /* The revision on which this transaction is based, or
 376      SVN_INVALID_REVISION if the transaction is not based on a
 377      revision at all */
 378   svn_revnum_t base_rev;
 379
 380   /* The ID of this transaction */
 381   const char *id;
 382
 383   /* FSAP-specific vtable and private data */
 384   txn_vtable_t *vtable;
 385   void *fsap_data;
 386 };
 387
 388
 389 struct svn_fs_root_t
 390 {
 391   /* A pool managing this root */
 392   apr_pool_t *pool;
 393
 394   /* The filesystem to which this root belongs */
 395   svn_fs_t *fs;
 396
 397   /* The kind of root this is */
 398   svn_boolean_t is_txn_root;
 399
 400   /* For transaction roots, the name of the transaction  */
 401   const char *txn;
 402
 403   /* For transaction roots, flags describing the txn's behavior. */
 404   apr_uint32_t txn_flags;
 405
 406   /* For revision roots, the number of the revision; for transaction
 407      roots, the number of the revision on which the transaction is
 408      based. */
 409   svn_revnum_t rev;
 410
 411   /* FSAP-specific vtable and private data */
 412   root_vtable_t *vtable;
 413   void *fsap_data;
 414 };
 415
 416
 417 struct svn_fs_history_t
 418 {
 419   /* FSAP-specific vtable and private data */
 420   history_vtable_t *vtable;
 421   void *fsap_data;
 422 };
 423
 424
 425 struct svn_fs_id_t
 426 {
 427   /* FSAP-specific vtable and private data */
 428   id_vtable_t *vtable;
 429   void *fsap_data;
 430 };
 431
 432
 433 struct svn_fs_access_t
 434 {
 435   /* An authenticated username using the fs */
 436   const char *username;
 437
 438   /* A collection of lock-tokens supplied by the fs caller.
 439      Hash maps (const char *) UUID --> (void *) 1
 440      fs functions should really only be interested whether a UUID
 441      exists as a hash key at all;  the value is irrelevant. */
 442   apr_hash_t *lock_tokens;
 443 };
 444
 445
 446
 447 #ifdef __cplusplus
 448 }
 449 #endif /* __cplusplus */
 450
 451 #endif