From 5a88871b9aff9d93a9cdba46fa52544d68010acf Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Thu, 1 Nov 2018 05:01:13 -0400 Subject: [PATCH] improve snapshot docs Using two snapshots from the same thread isn't really very easy to do, so we don't have to warn about that really (it's really nested use of snapshots that's a problem, and to do that you have to use thread-locals or something just to get the snapshot *into* the database -- at that point, something is really going wrong)). --- src/lib.rs | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 64c5740b..c9132417 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -288,11 +288,20 @@ pub trait ParallelDatabase: Database + Send { /// } /// ``` /// + /// # Panics + /// + /// It is not permitted to create a snapshot from inside of a + /// query. Attepting to do so will panic. + /// /// # Deadlock warning /// - /// This second handle is intended to be used from a separate - /// thread. Using two database handles from the **same thread** - /// can lead to deadlock. + /// The intended pattern for snapshots is that, once created, they + /// are sent to another thread and used from there. As such, the + /// `snapshot` acquires a "read lock" on the database -- + /// therefore, so long as the `snapshot` is not dropped, any + /// attempt to `set` a value in the database will block. If the + /// `snapshot` is owned by the same thread that is attempting to + /// `set`, this will cause a problem. fn snapshot(&self) -> Snapshot; }