GGLinnk/bees
1
0
Fork 0
mirror of https://github.com/Zygo/bees.git synced 2025-05-17 13:25:45 +02:00
Code Packages

docs: describe expected exceptions and impact of exception handling

Browse Source 
Add some docs about the exceptions that are less easy to suppress
directly.

Signed-off-by: Zygo Blaxell <bees@furryterror.org>
This commit is contained in:
Zygo Blaxell 2019-01-02 22:28:02 -05:00
parent be2c55119e
commit d583700962
1 changed files with 48 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
docs/gotchas.md
View File

@ -1,6 +1,54 @@
bees Gotchas
============
C++ Exceptions
--------------
bees is very paranoid about the data it gets from btrfs, and if btrfs
does anything bees does not expect, bees will throw an exception and move
on without touching the offending data. This will trigger a stack trace
to the log containing data which is useful for developers to understand
what happened.
In all cases C++ exceptions in bees are harmless to data on the
filesystem. bees handles most exceptions by aborting processing of
the current extent and moving to the next extent. In some cases an
exception may occur in a critical bees thread, which will stop the bees
process from making any further progress; however, these cases are rare
and are typically caused by unusual filesystem conditions (e.g. [freshly
formatted filesystem with no
data](https://github.com/Zygo/bees/issues/93)) or lack of memory or
other resources.
The following are common cases that users may encounter:
* If a snapshot is deleted, bees will generate a burst of exceptions for
references to files in the snapshot that no longer exist. This lasts
until the FD caches are cleared, usually a few minutes with default
btrfs mount options. These generally look like:
`std::system_error: BTRFS_IOC_TREE_SEARCH_V2: [path] at fs.cc:844: No such file or directory`
* If data is modified at the same time it is being scanned, bees will get
an inconsistent version of the data layout in the filesystem, causing
the `ExtentWalker` class to throw various constraint-check exceptions.
The exception causes bees to retry the extent in a later filesystem scan
(hopefully when the file is no longer being modified). The exception
text is similar to:
`std::runtime_error: fm.rbegin()->flags() = 776 failed constraint check (fm.rbegin()->flags() & FIEMAP_EXTENT_LAST) at extentwalker.cc:229`
but the line number or specific code fragment may vary.
* If there are too many possible matching blocks within a pair of extents,
bees will loop billions of times considering all possibilities. This is
a waste of time, so an exception is currently used to break out of such
loops early. The exception text in this case is:
`FIXME: bailing out here, need to fix this further up the call stack`
Snapshots
---------
@ -101,7 +149,3 @@ Other Gotchas
images), the deletion of the file can be delayed indefinitely.
To limit this delay, bees closes all FDs in its file FD cache every
10 btrfs transactions.
* If a snapshot is deleted, bees will generate a burst of exceptions
for references to files in the snapshot that no longer exist. This
lasts until the FD caches are cleared.