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_FS_H
26 #define LIBSVN_FS_FS_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,
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,
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 svn_error_t *svn_fs_base__init(const svn_version_t *loader_version,
188 fs_library_vtable_t **vtable,
189 apr_pool_t* common_pool);
190 svn_error_t *svn_fs_fs__init(const svn_version_t *loader_version,
191 fs_library_vtable_t **vtable,
192 apr_pool_t* common_pool);
193 svn_error_t *svn_fs_x__init(const svn_version_t *loader_version,
194 fs_library_vtable_t **vtable,
195 apr_pool_t* common_pool);
199 /*** vtable types for the abstract FS objects ***/
201 typedef struct fs_vtable_t
203 svn_error_t *(*youngest_rev)(svn_revnum_t *youngest_p, svn_fs_t *fs,
205 svn_error_t *(*revision_prop)(svn_string_t **value_p, svn_fs_t *fs,
206 svn_revnum_t rev, const char *propname,
208 svn_error_t *(*revision_proplist)(apr_hash_t **table_p, svn_fs_t *fs,
209 svn_revnum_t rev, apr_pool_t *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,
305 /* Generic node operations */
306 svn_error_t *(*check_path)(svn_node_kind_t *kind_p, svn_fs_root_t *root,
307 const char *path, apr_pool_t *pool);
308 svn_error_t *(*node_history)(svn_fs_history_t **history_p,
309 svn_fs_root_t *root, const char *path,
310 apr_pool_t *result_pool,
311 apr_pool_t *scratch_pool);
312 svn_error_t *(*node_id)(const svn_fs_id_t **id_p, svn_fs_root_t *root,
313 const char *path, apr_pool_t *pool);
314 svn_error_t *(*node_relation)(svn_fs_node_relation_t *relation,
315 svn_fs_root_t *root_a, const char *path_a,
316 svn_fs_root_t *root_b, const char *path_b,
317 apr_pool_t *scratch_pool);
318 svn_error_t *(*node_created_rev)(svn_revnum_t *revision,
319 svn_fs_root_t *root, const char *path,
321 svn_error_t *(*node_origin_rev)(svn_revnum_t *revision,
322 svn_fs_root_t *root, const char *path,
324 svn_error_t *(*node_created_path)(const char **created_path,
325 svn_fs_root_t *root, const char *path,
327 svn_error_t *(*delete_node)(svn_fs_root_t *root, const char *path,
329 svn_error_t *(*copy)(svn_fs_root_t *from_root, const char *from_path,
330 svn_fs_root_t *to_root, const char *to_path,
332 svn_error_t *(*revision_link)(svn_fs_root_t *from_root,
333 svn_fs_root_t *to_root,
336 svn_error_t *(*copied_from)(svn_revnum_t *rev_p, const char **path_p,
337 svn_fs_root_t *root, const char *path,
339 svn_error_t *(*closest_copy)(svn_fs_root_t **root_p, const char **path_p,
340 svn_fs_root_t *root, const char *path,
343 /* Property operations */
344 svn_error_t *(*node_prop)(svn_string_t **value_p, svn_fs_root_t *root,
345 const char *path, const char *propname,
347 svn_error_t *(*node_proplist)(apr_hash_t **table_p, svn_fs_root_t *root,
348 const char *path, apr_pool_t *pool);
349 svn_error_t *(*node_has_props)(svn_boolean_t *has_props, svn_fs_root_t *root,
350 const char *path, apr_pool_t *scratch_pool);
351 svn_error_t *(*change_node_prop)(svn_fs_root_t *root, const char *path,
353 const svn_string_t *value,
355 svn_error_t *(*props_changed)(int *changed_p, svn_fs_root_t *root1,
356 const char *path1, svn_fs_root_t *root2,
357 const char *path2, svn_boolean_t strict,
358 apr_pool_t *scratch_pool);
361 svn_error_t *(*dir_entries)(apr_hash_t **entries_p, svn_fs_root_t *root,
362 const char *path, apr_pool_t *pool);
363 svn_error_t *(*dir_optimal_order)(apr_array_header_t **ordered_p,
366 apr_pool_t *result_pool,
367 apr_pool_t *scratch_pool);
368 svn_error_t *(*make_dir)(svn_fs_root_t *root, const char *path,
372 svn_error_t *(*file_length)(svn_filesize_t *length_p, svn_fs_root_t *root,
373 const char *path, apr_pool_t *pool);
374 svn_error_t *(*file_checksum)(svn_checksum_t **checksum,
375 svn_checksum_kind_t kind, svn_fs_root_t *root,
376 const char *path, apr_pool_t *pool);
377 svn_error_t *(*file_contents)(svn_stream_t **contents,
378 svn_fs_root_t *root, const char *path,
380 svn_error_t *(*try_process_file_contents)(svn_boolean_t *success,
381 svn_fs_root_t *target_root,
382 const char *target_path,
383 svn_fs_process_contents_func_t processor,
386 svn_error_t *(*make_file)(svn_fs_root_t *root, const char *path,
388 svn_error_t *(*apply_textdelta)(svn_txdelta_window_handler_t *contents_p,
389 void **contents_baton_p,
390 svn_fs_root_t *root, const char *path,
391 svn_checksum_t *base_checksum,
392 svn_checksum_t *result_checksum,
394 svn_error_t *(*apply_text)(svn_stream_t **contents_p, svn_fs_root_t *root,
395 const char *path, svn_checksum_t *result_checksum,
397 svn_error_t *(*contents_changed)(int *changed_p, svn_fs_root_t *root1,
398 const char *path1, svn_fs_root_t *root2,
399 const char *path2, svn_boolean_t strict,
400 apr_pool_t *scratch_pool);
401 svn_error_t *(*get_file_delta_stream)(svn_txdelta_stream_t **stream_p,
402 svn_fs_root_t *source_root,
403 const char *source_path,
404 svn_fs_root_t *target_root,
405 const char *target_path,
409 svn_error_t *(*merge)(const char **conflict_p,
410 svn_fs_root_t *source_root,
411 const char *source_path,
412 svn_fs_root_t *target_root,
413 const char *target_path,
414 svn_fs_root_t *ancestor_root,
415 const char *ancestor_path,
418 svn_error_t *(*get_mergeinfo)(svn_mergeinfo_catalog_t *catalog,
420 const apr_array_header_t *paths,
421 svn_mergeinfo_inheritance_t inherit,
422 svn_boolean_t include_descendants,
423 svn_boolean_t adjust_inherited_mergeinfo,
424 apr_pool_t *result_pool,
425 apr_pool_t *scratch_pool);
429 typedef struct history_vtable_t
431 svn_error_t *(*prev)(svn_fs_history_t **prev_history_p,
432 svn_fs_history_t *history, svn_boolean_t cross_copies,
433 apr_pool_t *result_pool, apr_pool_t *scratch_pool);
434 svn_error_t *(*location)(const char **path, svn_revnum_t *revision,
435 svn_fs_history_t *history, apr_pool_t *pool);
439 typedef struct id_vtable_t
441 svn_string_t *(*unparse)(const svn_fs_id_t *id,
443 svn_fs_node_relation_t (*compare)(const svn_fs_id_t *a,
444 const svn_fs_id_t *b);
449 /*** Definitions of the abstract FS object types ***/
451 /* These are transaction properties that correspond to the bitfields
452 in the 'flags' argument to svn_fs_lock(). */
453 #define SVN_FS__PROP_TXN_CHECK_LOCKS SVN_PROP_PREFIX "check-locks"
454 #define SVN_FS__PROP_TXN_CHECK_OOD SVN_PROP_PREFIX "check-ood"
455 /* Set to "0" at the start of the txn, to "1" when svn:date changes. */
456 #define SVN_FS__PROP_TXN_CLIENT_DATE SVN_PROP_PREFIX "client-date"
460 /* The pool in which this fs object is allocated */
463 /* The path to the repository's top-level directory */
466 /* A callback for printing warning messages */
467 svn_fs_warning_callback_t warning;
470 /* The filesystem configuration */
473 /* An access context indicating who's using the fs */
474 svn_fs_access_t *access_ctx;
476 /* FSAP-specific vtable and private data */
480 /* UUID, stored by open(), create(), and set_uuid(). */
487 /* The filesystem to which this transaction belongs */
490 /* The revision on which this transaction is based, or
491 SVN_INVALID_REVISION if the transaction is not based on a
493 svn_revnum_t base_rev;
495 /* The ID of this transaction */
498 /* FSAP-specific vtable and private data */
499 txn_vtable_t *vtable;
506 /* A pool managing this root (and only this root!) */
509 /* The filesystem to which this root belongs */
512 /* The kind of root this is */
513 svn_boolean_t is_txn_root;
515 /* For transaction roots, the name of the transaction */
518 /* For transaction roots, flags describing the txn's behavior. */
519 apr_uint32_t txn_flags;
521 /* For revision roots, the number of the revision; for transaction
522 roots, the number of the revision on which the transaction is
526 /* FSAP-specific vtable and private data */
527 root_vtable_t *vtable;
532 struct svn_fs_history_t
534 /* FSAP-specific vtable and private data */
535 history_vtable_t *vtable;
542 /* FSAP-specific vtable and private data */
548 struct svn_fs_access_t
550 /* An authenticated username using the fs */
551 const char *username;
553 /* A collection of lock-tokens supplied by the fs caller.
554 Hash maps (const char *) UUID --> path where path can be the
555 magic value (void *) 1 if no path was specified.
556 fs functions should really only be interested whether a UUID
557 exists as a hash key at all; the value is irrelevant. */
558 apr_hash_t *lock_tokens;
561 struct svn_fs_lock_target_t
564 svn_revnum_t current_rev;
570 #endif /* __cplusplus */