Struct jammdb::Transaction [−][src]
An isolated view of the database
Transactions are how you can interact with the database.
They are created from a DB
,
and can be read-only or writable1 depending on the paramater you pass into the tx
method.
Transactions are completely isolated from each other, so a read-only transaction can expect the data to stay exactly the same for the life
of the transaction, regardless of how many changes are made in other transactions2.
There are four important methods. Check out their documentation for more details:
get_bucket
retreives buckets from the root level. Available in read-only or writable transactions.create_bucket
makes new buckets at the root level. Available in writable transactions only.detete_bucket
deletes a bucket (including all nested buckets) from the database. Available in writable transactions only.commit
saves a writable transaction. Available in writable transactions.
Trying to use the methods that require writable transactions from a read-only transaction will result in an error. If you make edits in a writable transaction,
and you want to save them, you must call the commit
method, otherwise when the transaction is dropped all your changes will be lost.
Examples
use jammdb::{DB, Data}; // create a read-only transaction let mut tx1 = db.tx(false)?; // create a writable transcation let mut tx2 = db.tx(true)?; // create a new bucket in the writable transaction tx2.create_bucket("new-bucket")?; // the read-only transaction will not be able to see the new bucket assert!(tx1.get_bucket("new-bucket").is_err()); // get a view of an existing bucket from both transactions let mut b1 = tx1.get_bucket("existing-bucket")?; let mut b2 = tx2.get_bucket("existing-bucket")?; // make an edit to the bucket b2.put("new-key", "new-value")?; // the read-only transaction will not have this new key assert_eq!(b1.get("new-key"), None); // but it will be able to see data that already existed! assert!(b1.get("existing-key").is_some());
1 There can only be a single writeable transaction at a time, so trying to open two writable transactions on the same thread will deadlock.
2 Keep in mind that long running read-only transactions will prevent the database from reclaiming old pages and your database may increase in disk size quickly if you're writing lots of data, so it's a good idea to keep transactions short.
Implementations
impl<'a> Transaction<'a>
[src]
pub fn get_bucket<T: AsRef<[u8]>>(
&'a self,
name: T
) -> Result<BucketRef<'_>, Error>
[src]
&'a self,
name: T
) -> Result<BucketRef<'_>, Error>
Returns a reference to the root level bucket with the given name.
Errors
Will return a BucketMissing
error if the bucket does not exist,
or an IncompatibleValue
error if the key exists but is not a bucket.
In a read-only transaction, you will get an error when trying to use any of the bucket's methods that modify data.
pub fn create_bucket<T: AsRef<[u8]>>(
&'a self,
name: T
) -> Result<BucketRef<'_>, Error>
[src]
&'a self,
name: T
) -> Result<BucketRef<'_>, Error>
Creates a new bucket with the given name and returns a reference it.
Errors
Will return a BucketExists
error if the bucket already exists,
an IncompatibleValue
error if the key exists but is not a bucket,
or a ReadOnlyTx
error if this is called on a read-only transaction.
pub fn get_or_create_bucket<T: AsRef<[u8]>>(
&self,
name: T
) -> Result<BucketRef<'_>, Error>
[src]
&self,
name: T
) -> Result<BucketRef<'_>, Error>
Creates an existing root-level bucket with the given name if it does not already exist. Gets the existing bucket if it does exist.
Errors
Will return an IncompatibleValue
error if the key exists but is not a bucket,
or a ReadOnlyTx
error if this is called on a read-only transaction.
pub fn delete_bucket<T: AsRef<[u8]>>(&self, name: T) -> Result<(), Error>
[src]
Deletes an existing root-level bucket with the given name
Errors
Will return a BucketMissing
error if the bucket does not exist,
an IncompatibleValue
error if the key exists but is not a bucket,
or a ReadOnlyTx
error if this is called on a read-only transaction.
pub fn commit(self) -> Result<(), Error>
[src]
Writes the changes made in the writeable transaction to the underlying file.
Errors
Will return an IOError
error if there are any io errors while writing to disk,
or a ReadOnlyTx
error if this is called on a read-only transaction.
Auto Trait Implementations
impl<'a> !RefUnwindSafe for Transaction<'a>
[src]
impl<'a> !Send for Transaction<'a>
[src]
impl<'a> !Sync for Transaction<'a>
[src]
impl<'a> Unpin for Transaction<'a>
[src]
impl<'a> !UnwindSafe for Transaction<'a>
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,