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);
163 svn_error_t *(*ioctl)(svn_fs_ioctl_code_t ctlcode,
164 void *input, void **output_p,
165 svn_cancel_func_t cancel_func,
167 apr_pool_t *result_pool,
168 apr_pool_t *scratch_pool);
169 } fs_library_vtable_t;
171 /* This is the type of symbol an FS module defines to fetch the
172 library vtable. The LOADER_VERSION parameter must remain first in
173 the list, and the function must use the C calling convention on all
174 platforms, so that the init functions can safely read the version
175 parameter. The COMMON_POOL parameter must be a pool with a greater
176 lifetime than the fs module so that fs global state can be kept
177 in it and cleaned up on termination before the fs module is unloaded.
178 Calls to these functions are globally serialized so that they have
179 exclusive access to the COMMON_POOL parameter.
181 ### need to force this to be __cdecl on Windows... how?? */
182 typedef svn_error_t *(*fs_init_func_t)(const svn_version_t *loader_version,
183 fs_library_vtable_t **vtable,
184 apr_pool_t* common_pool);
186 /* Here are the declarations for the FS module init functions. If we
187 are using DSO loading, they won't actually be linked into
188 libsvn_fs. Note that these private functions have a common_pool
189 parameter that may be used for fs module scoped variables such as
190 the bdb cache. This will be the same common_pool that is passed
191 to the create and open functions and these init functions (as well
192 as the open and create functions) are globally serialized so that
193 they have exclusive access to the common_pool. */
194 #include "../libsvn_fs_base/fs_init.h"
195 #include "../libsvn_fs_fs/fs_init.h"
196 #include "../libsvn_fs_x/fs_init.h"
200 /*** vtable types for the abstract FS objects ***/
202 typedef struct fs_vtable_t
204 svn_error_t *(*youngest_rev)(svn_revnum_t *youngest_p, svn_fs_t *fs,
206 svn_error_t *(*refresh_revprops)(svn_fs_t *fs, apr_pool_t *scratch_pool);
207 svn_error_t *(*revision_prop)(svn_string_t **value_p, svn_fs_t *fs,
208 svn_revnum_t rev, const char *propname,
209 svn_boolean_t refresh,
210 apr_pool_t *result_pool,
211 apr_pool_t *scratch_pool);
212 svn_error_t *(*revision_proplist)(apr_hash_t **table_p, svn_fs_t *fs,
214 svn_boolean_t refresh,
215 apr_pool_t *result_pool,
216 apr_pool_t *scratch_pool);
217 svn_error_t *(*change_rev_prop)(svn_fs_t *fs, svn_revnum_t rev,
219 const svn_string_t *const *old_value_p,
220 const svn_string_t *value,
222 /* There is no get_uuid(); see svn_fs_t.uuid docstring. */
223 svn_error_t *(*set_uuid)(svn_fs_t *fs, const char *uuid, apr_pool_t *pool);
224 svn_error_t *(*revision_root)(svn_fs_root_t **root_p, svn_fs_t *fs,
225 svn_revnum_t rev, apr_pool_t *pool);
226 svn_error_t *(*begin_txn)(svn_fs_txn_t **txn_p, svn_fs_t *fs,
227 svn_revnum_t rev, apr_uint32_t flags,
229 svn_error_t *(*open_txn)(svn_fs_txn_t **txn, svn_fs_t *fs,
230 const char *name, apr_pool_t *pool);
231 svn_error_t *(*purge_txn)(svn_fs_t *fs, const char *txn_id,
233 svn_error_t *(*list_transactions)(apr_array_header_t **names_p,
234 svn_fs_t *fs, apr_pool_t *pool);
235 svn_error_t *(*deltify)(svn_fs_t *fs, svn_revnum_t rev, apr_pool_t *pool);
236 svn_error_t *(*lock)(svn_fs_t *fs,
238 const char *comment, svn_boolean_t is_dav_comment,
239 apr_time_t expiration_date, svn_boolean_t steal_lock,
240 svn_fs_lock_callback_t lock_callback, void *lock_baton,
241 apr_pool_t *result_pool, apr_pool_t *scratch_pool);
242 svn_error_t *(*generate_lock_token)(const char **token, svn_fs_t *fs,
244 svn_error_t *(*unlock)(svn_fs_t *fs, apr_hash_t *targets,
245 svn_boolean_t break_lock,
246 svn_fs_lock_callback_t lock_callback, void *lock_baton,
247 apr_pool_t *result_pool, apr_pool_t *scratch_pool);
248 svn_error_t *(*get_lock)(svn_lock_t **lock, svn_fs_t *fs,
249 const char *path, apr_pool_t *pool);
250 svn_error_t *(*get_locks)(svn_fs_t *fs, const char *path, svn_depth_t depth,
251 svn_fs_get_locks_callback_t get_locks_func,
252 void *get_locks_baton,
254 svn_error_t *(*info_format)(int *fs_format,
255 svn_version_t **supports_version,
257 apr_pool_t *result_pool,
258 apr_pool_t *scratch_pool);
259 svn_error_t *(*info_config_files)(apr_array_header_t **files,
261 apr_pool_t *result_pool,
262 apr_pool_t *scratch_pool);
263 svn_error_t *(*info_fsap)(const void **fsap_info,
265 apr_pool_t *result_pool,
266 apr_pool_t *scratch_pool);
267 /* info_fsap_dup is in the library vtable. */
268 svn_error_t *(*verify_root)(svn_fs_root_t *root,
270 svn_error_t *(*freeze)(svn_fs_t *fs,
271 svn_fs_freeze_func_t freeze_func,
272 void *freeze_baton, apr_pool_t *pool);
273 svn_error_t *(*bdb_set_errcall)(svn_fs_t *fs,
274 void (*handler)(const char *errpfx,
276 svn_error_t *(*ioctl)(svn_fs_t *fs, svn_fs_ioctl_code_t ctlcode,
277 void *input, void **output_p,
278 svn_cancel_func_t cancel_func,
280 apr_pool_t *result_pool,
281 apr_pool_t *scratch_pool);
285 typedef struct txn_vtable_t
287 svn_error_t *(*commit)(const char **conflict_p, svn_revnum_t *new_rev,
288 svn_fs_txn_t *txn, apr_pool_t *pool);
289 svn_error_t *(*abort)(svn_fs_txn_t *txn, apr_pool_t *pool);
290 svn_error_t *(*get_prop)(svn_string_t **value_p, svn_fs_txn_t *txn,
291 const char *propname, apr_pool_t *pool);
292 svn_error_t *(*get_proplist)(apr_hash_t **table_p, svn_fs_txn_t *txn,
294 svn_error_t *(*change_prop)(svn_fs_txn_t *txn, const char *name,
295 const svn_string_t *value, apr_pool_t *pool);
296 svn_error_t *(*root)(svn_fs_root_t **root_p, svn_fs_txn_t *txn,
298 svn_error_t *(*change_props)(svn_fs_txn_t *txn, const apr_array_header_t *props,
303 /* Some of these operations accept multiple root arguments. Since the
304 roots may not all have the same vtable, we need a rule to determine
305 which root's vtable is used. The rule is: if one of the roots is
306 named "target", we use that root's vtable; otherwise, we use the
307 first root argument's vtable.
308 These callbacks correspond to svn_fs_* functions in include/svn_fs.h,
309 see there for details.
310 Note: delete_node() corresponds to svn_fs_delete(). */
311 typedef struct root_vtable_t
313 /* Determining what has changed in a root */
314 svn_error_t *(*paths_changed)(apr_hash_t **changed_paths_p,
317 svn_error_t *(*report_changes)(svn_fs_path_change_iterator_t **iterator,
319 apr_pool_t *result_pool,
320 apr_pool_t *scratch_pool);
322 /* Generic node operations */
323 svn_error_t *(*check_path)(svn_node_kind_t *kind_p, svn_fs_root_t *root,
324 const char *path, apr_pool_t *pool);
325 svn_error_t *(*node_history)(svn_fs_history_t **history_p,
326 svn_fs_root_t *root, const char *path,
327 apr_pool_t *result_pool,
328 apr_pool_t *scratch_pool);
329 svn_error_t *(*node_id)(const svn_fs_id_t **id_p, svn_fs_root_t *root,
330 const char *path, apr_pool_t *pool);
331 svn_error_t *(*node_relation)(svn_fs_node_relation_t *relation,
332 svn_fs_root_t *root_a, const char *path_a,
333 svn_fs_root_t *root_b, const char *path_b,
334 apr_pool_t *scratch_pool);
335 svn_error_t *(*node_created_rev)(svn_revnum_t *revision,
336 svn_fs_root_t *root, const char *path,
338 svn_error_t *(*node_origin_rev)(svn_revnum_t *revision,
339 svn_fs_root_t *root, const char *path,
341 svn_error_t *(*node_created_path)(const char **created_path,
342 svn_fs_root_t *root, const char *path,
344 svn_error_t *(*delete_node)(svn_fs_root_t *root, const char *path,
346 svn_error_t *(*copy)(svn_fs_root_t *from_root, const char *from_path,
347 svn_fs_root_t *to_root, const char *to_path,
349 svn_error_t *(*revision_link)(svn_fs_root_t *from_root,
350 svn_fs_root_t *to_root,
353 svn_error_t *(*copied_from)(svn_revnum_t *rev_p, const char **path_p,
354 svn_fs_root_t *root, const char *path,
356 svn_error_t *(*closest_copy)(svn_fs_root_t **root_p, const char **path_p,
357 svn_fs_root_t *root, const char *path,
360 /* Property operations */
361 svn_error_t *(*node_prop)(svn_string_t **value_p, svn_fs_root_t *root,
362 const char *path, const char *propname,
364 svn_error_t *(*node_proplist)(apr_hash_t **table_p, svn_fs_root_t *root,
365 const char *path, apr_pool_t *pool);
366 svn_error_t *(*node_has_props)(svn_boolean_t *has_props, svn_fs_root_t *root,
367 const char *path, apr_pool_t *scratch_pool);
368 svn_error_t *(*change_node_prop)(svn_fs_root_t *root, const char *path,
370 const svn_string_t *value,
372 svn_error_t *(*props_changed)(int *changed_p, svn_fs_root_t *root1,
373 const char *path1, svn_fs_root_t *root2,
374 const char *path2, svn_boolean_t strict,
375 apr_pool_t *scratch_pool);
378 svn_error_t *(*dir_entries)(apr_hash_t **entries_p, svn_fs_root_t *root,
379 const char *path, apr_pool_t *pool);
380 svn_error_t *(*dir_optimal_order)(apr_array_header_t **ordered_p,
383 apr_pool_t *result_pool,
384 apr_pool_t *scratch_pool);
385 svn_error_t *(*make_dir)(svn_fs_root_t *root, const char *path,
389 svn_error_t *(*file_length)(svn_filesize_t *length_p, svn_fs_root_t *root,
390 const char *path, apr_pool_t *pool);
391 svn_error_t *(*file_checksum)(svn_checksum_t **checksum,
392 svn_checksum_kind_t kind, svn_fs_root_t *root,
393 const char *path, apr_pool_t *pool);
394 svn_error_t *(*file_contents)(svn_stream_t **contents,
395 svn_fs_root_t *root, const char *path,
397 svn_error_t *(*try_process_file_contents)(svn_boolean_t *success,
398 svn_fs_root_t *target_root,
399 const char *target_path,
400 svn_fs_process_contents_func_t processor,
403 svn_error_t *(*make_file)(svn_fs_root_t *root, const char *path,
405 svn_error_t *(*apply_textdelta)(svn_txdelta_window_handler_t *contents_p,
406 void **contents_baton_p,
407 svn_fs_root_t *root, const char *path,
408 svn_checksum_t *base_checksum,
409 svn_checksum_t *result_checksum,
411 svn_error_t *(*apply_text)(svn_stream_t **contents_p, svn_fs_root_t *root,
412 const char *path, svn_checksum_t *result_checksum,
414 svn_error_t *(*contents_changed)(int *changed_p, svn_fs_root_t *root1,
415 const char *path1, svn_fs_root_t *root2,
416 const char *path2, svn_boolean_t strict,
417 apr_pool_t *scratch_pool);
418 svn_error_t *(*get_file_delta_stream)(svn_txdelta_stream_t **stream_p,
419 svn_fs_root_t *source_root,
420 const char *source_path,
421 svn_fs_root_t *target_root,
422 const char *target_path,
426 svn_error_t *(*merge)(const char **conflict_p,
427 svn_fs_root_t *source_root,
428 const char *source_path,
429 svn_fs_root_t *target_root,
430 const char *target_path,
431 svn_fs_root_t *ancestor_root,
432 const char *ancestor_path,
435 svn_error_t *(*get_mergeinfo)(svn_fs_root_t *root,
436 const apr_array_header_t *paths,
437 svn_mergeinfo_inheritance_t inherit,
438 svn_boolean_t include_descendants,
439 svn_boolean_t adjust_inherited_mergeinfo,
440 svn_fs_mergeinfo_receiver_t receiver,
442 apr_pool_t *scratch_pool);
446 typedef struct changes_iterator_vtable_t
448 svn_error_t *(*get)(svn_fs_path_change3_t **change,
449 svn_fs_path_change_iterator_t *iterator);
450 } changes_iterator_vtable_t;
453 typedef struct history_vtable_t
455 svn_error_t *(*prev)(svn_fs_history_t **prev_history_p,
456 svn_fs_history_t *history, svn_boolean_t cross_copies,
457 apr_pool_t *result_pool, apr_pool_t *scratch_pool);
458 svn_error_t *(*location)(const char **path, svn_revnum_t *revision,
459 svn_fs_history_t *history, apr_pool_t *pool);
463 typedef struct id_vtable_t
465 svn_string_t *(*unparse)(const svn_fs_id_t *id,
467 svn_fs_node_relation_t (*compare)(const svn_fs_id_t *a,
468 const svn_fs_id_t *b);
473 /*** Definitions of the abstract FS object types ***/
475 /* These are transaction properties that correspond to the bitfields
476 in the 'flags' argument to svn_fs_begin_txn2(). */
477 #define SVN_FS__PROP_TXN_CHECK_LOCKS SVN_PROP_PREFIX "check-locks"
478 #define SVN_FS__PROP_TXN_CHECK_OOD SVN_PROP_PREFIX "check-ood"
479 /* Set to "0" at the start of the txn, to "1" when svn:date changes. */
480 #define SVN_FS__PROP_TXN_CLIENT_DATE SVN_PROP_PREFIX "client-date"
484 /* The pool in which this fs object is allocated */
487 /* The path to the repository's top-level directory */
490 /* A callback for printing warning messages */
491 svn_fs_warning_callback_t warning;
494 /* The filesystem configuration */
497 /* An access context indicating who's using the fs */
498 svn_fs_access_t *access_ctx;
500 /* FSAP-specific vtable and private data */
501 const fs_vtable_t *vtable;
504 /* UUID, stored by open(), create(), and set_uuid(). */
511 /* The filesystem to which this transaction belongs */
514 /* The revision on which this transaction is based, or
515 SVN_INVALID_REVISION if the transaction is not based on a
517 svn_revnum_t base_rev;
519 /* The ID of this transaction */
522 /* FSAP-specific vtable and private data */
523 const txn_vtable_t *vtable;
530 /* A pool managing this root (and only this root!) */
533 /* The filesystem to which this root belongs */
536 /* The kind of root this is */
537 svn_boolean_t is_txn_root;
539 /* For transaction roots, the name of the transaction */
542 /* For transaction roots, flags describing the txn's behavior. */
543 apr_uint32_t txn_flags;
545 /* For revision roots, the number of the revision; for transaction
546 roots, the number of the revision on which the transaction is
550 /* FSAP-specific vtable and private data */
551 const root_vtable_t *vtable;
555 struct svn_fs_path_change_iterator_t
557 /* FSAP-specific vtable and private data */
558 const changes_iterator_vtable_t *vtable;
562 struct svn_fs_history_t
564 /* FSAP-specific vtable and private data */
565 const history_vtable_t *vtable;
572 /* FSAP-specific vtable and private data */
573 const id_vtable_t *vtable;
578 struct svn_fs_access_t
580 /* An authenticated username using the fs */
581 const char *username;
583 /* A collection of lock-tokens supplied by the fs caller.
584 Hash maps (const char *) UUID --> path where path can be the
585 magic value (void *) 1 if no path was specified.
586 fs functions should really only be interested whether a UUID
587 exists as a hash key at all; the value is irrelevant. */
588 apr_hash_t *lock_tokens;
591 struct svn_fs_lock_target_t
594 svn_revnum_t current_rev;
600 #endif /* __cplusplus */
602 #endif /* LIBSVN_FS_LOADER_H */