2 * fs_loader.h: Declarations for the FS loader library
4 * ====================================================================
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
21 * ====================================================================
25 #ifndef LIBSVN_FS_LOADER_H
26 #define LIBSVN_FS_LOADER_H
28 #include "svn_types.h"
30 #include "svn_props.h"
31 #include "private/svn_mutex.h"
35 #endif /* __cplusplus */
38 /* The FS loader library implements the a front end to "filesystem
39 abstract providers" (FSAPs), which implement the svn_fs API.
41 The loader library divides up the FS API into several categories:
43 - Top-level functions, which operate on paths to an FS
44 - Functions which operate on an FS object
45 - Functions which operate on a transaction object
46 - Functions which operate on a root object
47 - Functions which operate on a history object
48 - Functions which operate on a noderev-ID object
50 Some generic fields of the FS, transaction, root, and history
51 objects are defined by the loader library; the rest are stored in
52 the "fsap_data" field which is defined by the FSAP. Likewise, some
53 of the very simple svn_fs API functions (such as svn_fs_root_fs)
54 are defined by the loader library, while the rest are implemented
55 through vtable calls defined by the FSAP.
57 If you are considering writing a new database-backed filesystem
58 implementation, it may be appropriate to add a second, lower-level
59 abstraction to the libsvn_fs_base library which currently
60 implements the BDB filesystem type. Consult the dev list for
61 details on the "FSP-level" abstraction concept.
66 /*** Top-level library vtable type ***/
68 typedef struct fs_library_vtable_t
70 /* This field should always remain first in the vtable.
71 Apart from that, it can be changed however you like, since exact
72 version equality is required between loader and module. This policy
73 was weaker during 1.1.x, but only in ways which do not conflict with
74 this statement, now that the minor version has increased. */
75 const svn_version_t *(*get_version)(void);
77 /* The open_fs/create/open_fs_for_recovery/upgrade_fs functions must
78 use the common_pool_lock to serialize the access to the common_pool
79 parameter for allocating fs-global objects such as an env cache. */
80 svn_error_t *(*create)(svn_fs_t *fs, const char *path,
81 svn_mutex__t *common_pool_lock,
82 apr_pool_t *scratch_pool,
83 apr_pool_t *common_pool);
84 svn_error_t *(*open_fs)(svn_fs_t *fs, const char *path,
85 svn_mutex__t *common_pool_lock,
86 apr_pool_t *scratch_pool,
87 apr_pool_t *common_pool);
88 /* open_for_recovery() is like open(), but used to fill in an fs pointer
89 that will be passed to recover(). We assume that the open() method
90 might not be immediately appropriate for recovery. */
91 svn_error_t *(*open_fs_for_recovery)(svn_fs_t *fs, const char *path,
92 svn_mutex__t *common_pool_lock,
94 apr_pool_t *common_pool);
95 svn_error_t *(*upgrade_fs)(svn_fs_t *fs,
97 svn_fs_upgrade_notify_t notify_func,
99 svn_cancel_func_t cancel_func,
101 svn_mutex__t *common_pool_lock,
102 apr_pool_t *scratch_pool,
103 apr_pool_t *common_pool);
104 svn_error_t *(*verify_fs)(svn_fs_t *fs, const char *path,
107 svn_fs_progress_notify_func_t notify_func,
109 svn_cancel_func_t cancel_func,
111 svn_mutex__t *common_pool_lock,
113 apr_pool_t *common_pool);
114 svn_error_t *(*delete_fs)(const char *path, apr_pool_t *pool);
115 svn_error_t *(*hotcopy)(svn_fs_t *src_fs,
117 const char *src_path,
118 const char *dst_path,
120 svn_boolean_t incremental,
121 svn_fs_hotcopy_notify_t notify_func,
123 svn_cancel_func_t cancel_func,
125 svn_mutex__t *common_pool_lock,
127 apr_pool_t *common_pool);
128 const char *(*get_description)(void);
129 svn_error_t *(*recover)(svn_fs_t *fs,
130 svn_cancel_func_t cancel_func, void *cancel_baton,
132 svn_error_t *(*pack_fs)(svn_fs_t *fs, const char *path,
133 svn_fs_pack_notify_t notify_func, void *notify_baton,
134 svn_cancel_func_t cancel_func, void *cancel_baton,
135 svn_mutex__t *common_pool_lock,
136 apr_pool_t *pool, apr_pool_t *common_pool);
138 /* Provider-specific functions should go here, even if they could go
139 in an object vtable, so that they are all kept together. */
140 svn_error_t *(*bdb_logfiles)(apr_array_header_t **logfiles,
141 const char *path, svn_boolean_t only_unused,
144 /* This is to let the base provider implement the deprecated
145 svn_fs_parse_id, which we've decided doesn't belong in the FS
146 API. If we change our minds and decide to add a real
147 svn_fs_parse_id variant which takes an FS object, it should go
148 into the FS vtable. */
149 svn_fs_id_t *(*parse_id)(const char *data, apr_size_t len,
151 /* Allow an FSAP to call svn_fs_open(), which is in a higher-level library
152 (libsvn_fs-1.so) and cannot easily be moved to libsvn_fs_util. */
153 svn_error_t *(*set_svn_fs_open)(svn_fs_t *fs,
154 svn_error_t *(*svn_fs_open_)(svn_fs_t **,
159 /* For svn_fs_info_fsfs_dup(). */
160 void *(*info_fsap_dup)(const void *fsap_info,
161 apr_pool_t *result_pool);
162 } fs_library_vtable_t;
164 /* This is the type of symbol an FS module defines to fetch the
165 library vtable. The LOADER_VERSION parameter must remain first in
166 the list, and the function must use the C calling convention on all
167 platforms, so that the init functions can safely read the version
168 parameter. The COMMON_POOL parameter must be a pool with a greater
169 lifetime than the fs module so that fs global state can be kept
170 in it and cleaned up on termination before the fs module is unloaded.
171 Calls to these functions are globally serialized so that they have
172 exclusive access to the COMMON_POOL parameter.
174 ### need to force this to be __cdecl on Windows... how?? */
175 typedef svn_error_t *(*fs_init_func_t)(const svn_version_t *loader_version,
176 fs_library_vtable_t **vtable,
177 apr_pool_t* common_pool);
179 /* Here are the declarations for the FS module init functions. If we
180 are using DSO loading, they won't actually be linked into
181 libsvn_fs. Note that these private functions have a common_pool
182 parameter that may be used for fs module scoped variables such as
183 the bdb cache. This will be the same common_pool that is passed
184 to the create and open functions and these init functions (as well
185 as the open and create functions) are globally serialized so that
186 they have exclusive access to the common_pool. */
187 #include "../libsvn_fs_base/fs_init.h"
188 #include "../libsvn_fs_fs/fs_init.h"
189 #include "../libsvn_fs_x/fs_init.h"
193 /*** vtable types for the abstract FS objects ***/
195 typedef struct fs_vtable_t
197 svn_error_t *(*youngest_rev)(svn_revnum_t *youngest_p, svn_fs_t *fs,
199 svn_error_t *(*refresh_revprops)(svn_fs_t *fs, apr_pool_t *scratch_pool);
200 svn_error_t *(*revision_prop)(svn_string_t **value_p, svn_fs_t *fs,
201 svn_revnum_t rev, const char *propname,
202 svn_boolean_t refresh,
203 apr_pool_t *result_pool,
204 apr_pool_t *scratch_pool);
205 svn_error_t *(*revision_proplist)(apr_hash_t **table_p, svn_fs_t *fs,
207 svn_boolean_t refresh,
208 apr_pool_t *result_pool,
209 apr_pool_t *scratch_pool);
210 svn_error_t *(*change_rev_prop)(svn_fs_t *fs, svn_revnum_t rev,
212 const svn_string_t *const *old_value_p,
213 const svn_string_t *value,
215 /* There is no get_uuid(); see svn_fs_t.uuid docstring. */
216 svn_error_t *(*set_uuid)(svn_fs_t *fs, const char *uuid, apr_pool_t *pool);
217 svn_error_t *(*revision_root)(svn_fs_root_t **root_p, svn_fs_t *fs,
218 svn_revnum_t rev, apr_pool_t *pool);
219 svn_error_t *(*begin_txn)(svn_fs_txn_t **txn_p, svn_fs_t *fs,
220 svn_revnum_t rev, apr_uint32_t flags,
222 svn_error_t *(*open_txn)(svn_fs_txn_t **txn, svn_fs_t *fs,
223 const char *name, apr_pool_t *pool);
224 svn_error_t *(*purge_txn)(svn_fs_t *fs, const char *txn_id,
226 svn_error_t *(*list_transactions)(apr_array_header_t **names_p,
227 svn_fs_t *fs, apr_pool_t *pool);
228 svn_error_t *(*deltify)(svn_fs_t *fs, svn_revnum_t rev, apr_pool_t *pool);
229 svn_error_t *(*lock)(svn_fs_t *fs,
231 const char *comment, svn_boolean_t is_dav_comment,
232 apr_time_t expiration_date, svn_boolean_t steal_lock,
233 svn_fs_lock_callback_t lock_callback, void *lock_baton,
234 apr_pool_t *result_pool, apr_pool_t *scratch_pool);
235 svn_error_t *(*generate_lock_token)(const char **token, svn_fs_t *fs,
237 svn_error_t *(*unlock)(svn_fs_t *fs, apr_hash_t *targets,
238 svn_boolean_t break_lock,
239 svn_fs_lock_callback_t lock_callback, void *lock_baton,
240 apr_pool_t *result_pool, apr_pool_t *scratch_pool);
241 svn_error_t *(*get_lock)(svn_lock_t **lock, svn_fs_t *fs,
242 const char *path, apr_pool_t *pool);
243 svn_error_t *(*get_locks)(svn_fs_t *fs, const char *path, svn_depth_t depth,
244 svn_fs_get_locks_callback_t get_locks_func,
245 void *get_locks_baton,
247 svn_error_t *(*info_format)(int *fs_format,
248 svn_version_t **supports_version,
250 apr_pool_t *result_pool,
251 apr_pool_t *scratch_pool);
252 svn_error_t *(*info_config_files)(apr_array_header_t **files,
254 apr_pool_t *result_pool,
255 apr_pool_t *scratch_pool);
256 svn_error_t *(*info_fsap)(const void **fsap_info,
258 apr_pool_t *result_pool,
259 apr_pool_t *scratch_pool);
260 /* info_fsap_dup is in the library vtable. */
261 svn_error_t *(*verify_root)(svn_fs_root_t *root,
263 svn_error_t *(*freeze)(svn_fs_t *fs,
264 svn_fs_freeze_func_t freeze_func,
265 void *freeze_baton, apr_pool_t *pool);
266 svn_error_t *(*bdb_set_errcall)(svn_fs_t *fs,
267 void (*handler)(const char *errpfx,
272 typedef struct txn_vtable_t
274 svn_error_t *(*commit)(const char **conflict_p, svn_revnum_t *new_rev,
275 svn_fs_txn_t *txn, apr_pool_t *pool);
276 svn_error_t *(*abort)(svn_fs_txn_t *txn, apr_pool_t *pool);
277 svn_error_t *(*get_prop)(svn_string_t **value_p, svn_fs_txn_t *txn,
278 const char *propname, apr_pool_t *pool);
279 svn_error_t *(*get_proplist)(apr_hash_t **table_p, svn_fs_txn_t *txn,
281 svn_error_t *(*change_prop)(svn_fs_txn_t *txn, const char *name,
282 const svn_string_t *value, apr_pool_t *pool);
283 svn_error_t *(*root)(svn_fs_root_t **root_p, svn_fs_txn_t *txn,
285 svn_error_t *(*change_props)(svn_fs_txn_t *txn, const apr_array_header_t *props,
290 /* Some of these operations accept multiple root arguments. Since the
291 roots may not all have the same vtable, we need a rule to determine
292 which root's vtable is used. The rule is: if one of the roots is
293 named "target", we use that root's vtable; otherwise, we use the
294 first root argument's vtable.
295 These callbacks correspond to svn_fs_* functions in include/svn_fs.h,
296 see there for details.
297 Note: delete_node() corresponds to svn_fs_delete(). */
298 typedef struct root_vtable_t
300 /* Determining what has changed in a root */
301 svn_error_t *(*paths_changed)(apr_hash_t **changed_paths_p,
304 svn_error_t *(*report_changes)(svn_fs_path_change_iterator_t **iterator,
306 apr_pool_t *result_pool,
307 apr_pool_t *scratch_pool);
309 /* Generic node operations */
310 svn_error_t *(*check_path)(svn_node_kind_t *kind_p, svn_fs_root_t *root,
311 const char *path, apr_pool_t *pool);
312 svn_error_t *(*node_history)(svn_fs_history_t **history_p,
313 svn_fs_root_t *root, const char *path,
314 apr_pool_t *result_pool,
315 apr_pool_t *scratch_pool);
316 svn_error_t *(*node_id)(const svn_fs_id_t **id_p, svn_fs_root_t *root,
317 const char *path, apr_pool_t *pool);
318 svn_error_t *(*node_relation)(svn_fs_node_relation_t *relation,
319 svn_fs_root_t *root_a, const char *path_a,
320 svn_fs_root_t *root_b, const char *path_b,
321 apr_pool_t *scratch_pool);
322 svn_error_t *(*node_created_rev)(svn_revnum_t *revision,
323 svn_fs_root_t *root, const char *path,
325 svn_error_t *(*node_origin_rev)(svn_revnum_t *revision,
326 svn_fs_root_t *root, const char *path,
328 svn_error_t *(*node_created_path)(const char **created_path,
329 svn_fs_root_t *root, const char *path,
331 svn_error_t *(*delete_node)(svn_fs_root_t *root, const char *path,
333 svn_error_t *(*copy)(svn_fs_root_t *from_root, const char *from_path,
334 svn_fs_root_t *to_root, const char *to_path,
336 svn_error_t *(*revision_link)(svn_fs_root_t *from_root,
337 svn_fs_root_t *to_root,
340 svn_error_t *(*copied_from)(svn_revnum_t *rev_p, const char **path_p,
341 svn_fs_root_t *root, const char *path,
343 svn_error_t *(*closest_copy)(svn_fs_root_t **root_p, const char **path_p,
344 svn_fs_root_t *root, const char *path,
347 /* Property operations */
348 svn_error_t *(*node_prop)(svn_string_t **value_p, svn_fs_root_t *root,
349 const char *path, const char *propname,
351 svn_error_t *(*node_proplist)(apr_hash_t **table_p, svn_fs_root_t *root,
352 const char *path, apr_pool_t *pool);
353 svn_error_t *(*node_has_props)(svn_boolean_t *has_props, svn_fs_root_t *root,
354 const char *path, apr_pool_t *scratch_pool);
355 svn_error_t *(*change_node_prop)(svn_fs_root_t *root, const char *path,
357 const svn_string_t *value,
359 svn_error_t *(*props_changed)(int *changed_p, svn_fs_root_t *root1,
360 const char *path1, svn_fs_root_t *root2,
361 const char *path2, svn_boolean_t strict,
362 apr_pool_t *scratch_pool);
365 svn_error_t *(*dir_entries)(apr_hash_t **entries_p, svn_fs_root_t *root,
366 const char *path, apr_pool_t *pool);
367 svn_error_t *(*dir_optimal_order)(apr_array_header_t **ordered_p,
370 apr_pool_t *result_pool,
371 apr_pool_t *scratch_pool);
372 svn_error_t *(*make_dir)(svn_fs_root_t *root, const char *path,
376 svn_error_t *(*file_length)(svn_filesize_t *length_p, svn_fs_root_t *root,
377 const char *path, apr_pool_t *pool);
378 svn_error_t *(*file_checksum)(svn_checksum_t **checksum,
379 svn_checksum_kind_t kind, svn_fs_root_t *root,
380 const char *path, apr_pool_t *pool);
381 svn_error_t *(*file_contents)(svn_stream_t **contents,
382 svn_fs_root_t *root, const char *path,
384 svn_error_t *(*try_process_file_contents)(svn_boolean_t *success,
385 svn_fs_root_t *target_root,
386 const char *target_path,
387 svn_fs_process_contents_func_t processor,
390 svn_error_t *(*make_file)(svn_fs_root_t *root, const char *path,
392 svn_error_t *(*apply_textdelta)(svn_txdelta_window_handler_t *contents_p,
393 void **contents_baton_p,
394 svn_fs_root_t *root, const char *path,
395 svn_checksum_t *base_checksum,
396 svn_checksum_t *result_checksum,
398 svn_error_t *(*apply_text)(svn_stream_t **contents_p, svn_fs_root_t *root,
399 const char *path, svn_checksum_t *result_checksum,
401 svn_error_t *(*contents_changed)(int *changed_p, svn_fs_root_t *root1,
402 const char *path1, svn_fs_root_t *root2,
403 const char *path2, svn_boolean_t strict,
404 apr_pool_t *scratch_pool);
405 svn_error_t *(*get_file_delta_stream)(svn_txdelta_stream_t **stream_p,
406 svn_fs_root_t *source_root,
407 const char *source_path,
408 svn_fs_root_t *target_root,
409 const char *target_path,
413 svn_error_t *(*merge)(const char **conflict_p,
414 svn_fs_root_t *source_root,
415 const char *source_path,
416 svn_fs_root_t *target_root,
417 const char *target_path,
418 svn_fs_root_t *ancestor_root,
419 const char *ancestor_path,
422 svn_error_t *(*get_mergeinfo)(svn_fs_root_t *root,
423 const apr_array_header_t *paths,
424 svn_mergeinfo_inheritance_t inherit,
425 svn_boolean_t include_descendants,
426 svn_boolean_t adjust_inherited_mergeinfo,
427 svn_fs_mergeinfo_receiver_t receiver,
429 apr_pool_t *scratch_pool);
433 typedef struct changes_iterator_vtable_t
435 svn_error_t *(*get)(svn_fs_path_change3_t **change,
436 svn_fs_path_change_iterator_t *iterator);
437 } changes_iterator_vtable_t;
440 typedef struct history_vtable_t
442 svn_error_t *(*prev)(svn_fs_history_t **prev_history_p,
443 svn_fs_history_t *history, svn_boolean_t cross_copies,
444 apr_pool_t *result_pool, apr_pool_t *scratch_pool);
445 svn_error_t *(*location)(const char **path, svn_revnum_t *revision,
446 svn_fs_history_t *history, apr_pool_t *pool);
450 typedef struct id_vtable_t
452 svn_string_t *(*unparse)(const svn_fs_id_t *id,
454 svn_fs_node_relation_t (*compare)(const svn_fs_id_t *a,
455 const svn_fs_id_t *b);
460 /*** Definitions of the abstract FS object types ***/
462 /* These are transaction properties that correspond to the bitfields
463 in the 'flags' argument to svn_fs_begin_txn2(). */
464 #define SVN_FS__PROP_TXN_CHECK_LOCKS SVN_PROP_PREFIX "check-locks"
465 #define SVN_FS__PROP_TXN_CHECK_OOD SVN_PROP_PREFIX "check-ood"
466 /* Set to "0" at the start of the txn, to "1" when svn:date changes. */
467 #define SVN_FS__PROP_TXN_CLIENT_DATE SVN_PROP_PREFIX "client-date"
471 /* The pool in which this fs object is allocated */
474 /* The path to the repository's top-level directory */
477 /* A callback for printing warning messages */
478 svn_fs_warning_callback_t warning;
481 /* The filesystem configuration */
484 /* An access context indicating who's using the fs */
485 svn_fs_access_t *access_ctx;
487 /* FSAP-specific vtable and private data */
488 const fs_vtable_t *vtable;
491 /* UUID, stored by open(), create(), and set_uuid(). */
498 /* The filesystem to which this transaction belongs */
501 /* The revision on which this transaction is based, or
502 SVN_INVALID_REVISION if the transaction is not based on a
504 svn_revnum_t base_rev;
506 /* The ID of this transaction */
509 /* FSAP-specific vtable and private data */
510 const txn_vtable_t *vtable;
517 /* A pool managing this root (and only this root!) */
520 /* The filesystem to which this root belongs */
523 /* The kind of root this is */
524 svn_boolean_t is_txn_root;
526 /* For transaction roots, the name of the transaction */
529 /* For transaction roots, flags describing the txn's behavior. */
530 apr_uint32_t txn_flags;
532 /* For revision roots, the number of the revision; for transaction
533 roots, the number of the revision on which the transaction is
537 /* FSAP-specific vtable and private data */
538 const root_vtable_t *vtable;
542 struct svn_fs_path_change_iterator_t
544 /* FSAP-specific vtable and private data */
545 const changes_iterator_vtable_t *vtable;
549 struct svn_fs_history_t
551 /* FSAP-specific vtable and private data */
552 const history_vtable_t *vtable;
559 /* FSAP-specific vtable and private data */
560 const id_vtable_t *vtable;
565 struct svn_fs_access_t
567 /* An authenticated username using the fs */
568 const char *username;
570 /* A collection of lock-tokens supplied by the fs caller.
571 Hash maps (const char *) UUID --> path where path can be the
572 magic value (void *) 1 if no path was specified.
573 fs functions should really only be interested whether a UUID
574 exists as a hash key at all; the value is irrelevant. */
575 apr_hash_t *lock_tokens;
578 struct svn_fs_lock_target_t
581 svn_revnum_t current_rev;
587 #endif /* __cplusplus */
589 #endif /* LIBSVN_FS_LOADER_H */