makary/bookmarkfs
1
0
Fork 0
mirror of https://git.sr.ht/~cismonx/bookmarkfs synced 2025-06-07 19:58:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: explain exlusive mode in backend API docs

Browse source 
Add add cross references when appropriate.
This commit is contained in:
CismonX 2025-03-27 12:12:30 +08:00
parent 2e3685f217
commit 86c7af8f6f
No known key found for this signature in database
GPG key ID: 3094873E29A482FB
1 changed files with 28 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
doc/bookmarkfs.texi
View file

@ -899,6 +899,7 @@ The error may occur when the underlying bookmark storage has been modified by
another process (e.g., a web browser) after opening a file. another process (e.g., a web browser) after opening a file.
If the filesystem is mounted in exclusive mode, this error should not occur. If the filesystem is mounted in exclusive mode, this error should not occur.
@xref{Exclusive Mode}.
@end table @end table
Other BookmarkFS-specific errors may occur. Other BookmarkFS-specific errors may occur.
@ -1300,6 +1301,9 @@ If you wish to mount the bookmarks while keeping the browser session open,
set the @samp{storage.sqlite.exclusiveLock.enabled} browser preference set the @samp{storage.sqlite.exclusiveLock.enabled} browser preference
to @samp{false}. to @samp{false}.
The @option{lock=exclusive} option also enables exclusive mode
(@pxref{Exclusive Mode}).
@item assume_title_distinct @item assume_title_distinct
If this options is provided, the backend assumes that bookmark names are If this options is provided, the backend assumes that bookmark names are
distinct under the same bookmark folder. distinct under the same bookmark folder.
@ -1438,8 +1442,10 @@ or a ``fallback'' one which is less efficient but more portable.
@item none @item none
Do not watch for changes of the bookmark storage. Do not watch for changes of the bookmark storage.
With @option{watcher=none}, external changes to the bookmark storage are not External changes are not visible to the BookmarkFS filesystem,
visible to the BookmarkFS filesystem. and will be lost if the backend writes to the bookmark storage.
This option also enables exclusive mode (@pxref{Exclusive Mode}).
@end table @end table
@end table @end table
@ -1593,6 +1599,21 @@ argument, usually named @code{callback}, to be invoked by the backend.
It is guaranteed that backend functions are never called from within It is guaranteed that backend functions are never called from within
a callback function. a callback function.
@anchor{Exclusive Mode}
@cindex Exclusive Mode
@item Exclusive Mode
If exclusive mode is enabled for a backend context,
modifications to the corresponding bookmark storage should only be performed
by calling backend functions on the current context.
If the bookmark storage is modified by other means, filesystem and backend
behavior is undefined.
Frontend programs may perform optimizations based on this assumption.
The backend decides whether exclusive mode should be enabled for a context
during @code{backend_create} (@pxref{Create Backend Context}),
by setting the @code{BOOKMARKFS_BACKEND_EXCLUSIVE} response flag.
@item Error Codes @item Error Codes
Some backend functions return an error code on failure instead of Some backend functions return an error code on failure instead of
just @code{-1}. just @code{-1}.
@ -1778,9 +1799,9 @@ Indicates that the @option{-o no_landlock} option is given to
@item BOOKMARKFS_BACKEND_FSCK_ONLY @item BOOKMARKFS_BACKEND_FSCK_ONLY
Indicates that the backend is launched from @command{fsck.bookmarkfs}. Indicates that the backend is launched from @command{fsck.bookmarkfs}.
The backend must claim exclusive access to the bookmark storage, and only Exclusive mode must be enabled for this context (@pxref{Exclusive Mode}), and
the @code{bookmark_lookup}, @code{bookmark_list}, @code{bookmark_check} only the @code{bookmark_lookup}, @code{bookmark_list}, @code{bookmark_check}
and @code{bookmark_sync} functions will be called on the bookmarks. and @code{bookmark_sync} functions will be called on the bookmark objects.
@end table @end table
@item store_path @item store_path
@ -1898,10 +1919,7 @@ A bit array of the following flags:
@table @code @table @code
@item BOOKMARKFS_BACKEND_EXCLUSIVE @item BOOKMARKFS_BACKEND_EXCLUSIVE
Indicates that the backend claims exclusive access to the bookmark storage. Indicates that the backend claims exclusive access to the bookmark storage.
@xref{Exclusive Mode}.
In exclusive mode, modifications to the bookmark storage only come from
the frontend, and the caller may perform optimizations based on
this assumption.
@item BOOKMARKFS_BACKEND_HAS_KEYWORD @item BOOKMARKFS_BACKEND_HAS_KEYWORD
Indicates that the backend supports keywords for this context. Indicates that the backend supports keywords for this context.
@ -2405,6 +2423,7 @@ If this error code is returned, @code{callback} must not be called.
which has access to the bookmark storage. which has access to the bookmark storage.
In exclusive mode, this is not expected to happen, and @code{bookmark_list} In exclusive mode, this is not expected to happen, and @code{bookmark_list}
is always called with a @code{cookie_ptr} of @code{NULL} value. is always called with a @code{cookie_ptr} of @code{NULL} value.
@xref{Exclusive Mode}.
If changes cannot be detected in an efficient way, false positives are If changes cannot be detected in an efficient way, false positives are
acceptable. acceptable.