rocksdb/
column_family.rs

1// Copyright 2020 Tyler Neely
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use crate::{db::MultiThreaded, ffi, Options};
16
17use std::sync::Arc;
18
19/// The name of the default column family.
20///
21/// The column family with this name is created implicitly whenever column
22/// families are used.
23pub const DEFAULT_COLUMN_FAMILY_NAME: &str = "default";
24
25/// A descriptor for a RocksDB column family.
26///
27/// A description of the column family, containing the name and `Options`.
28pub struct ColumnFamilyDescriptor {
29    pub(crate) name: String,
30    pub(crate) options: Options,
31}
32
33impl ColumnFamilyDescriptor {
34    // Create a new column family descriptor with the specified name and options.
35    pub fn new<S>(name: S, options: Options) -> Self
36    where
37        S: Into<String>,
38    {
39        Self {
40            name: name.into(),
41            options,
42        }
43    }
44
45    /// Get the name of the ColumnFamilyDescriptor.
46    pub fn name(&self) -> &str {
47        &self.name
48    }
49}
50
51/// An opaque type used to represent a column family. Returned from some functions, and used
52/// in others
53pub struct ColumnFamily {
54    pub(crate) inner: *mut ffi::rocksdb_column_family_handle_t,
55}
56
57/// A specialized opaque type used to represent a column family by the [`MultiThreaded`]
58/// mode. Clone (and Copy) is derived to behave like `&ColumnFamily` (this is used for
59/// single-threaded mode). `Clone`/`Copy` is safe because this lifetime is bound to DB like
60/// iterators/snapshots. On top of it, this is as cheap and small as `&ColumnFamily` because
61/// this only has a single pointer-wide field.
62pub struct BoundColumnFamily<'a> {
63    pub(crate) inner: *mut ffi::rocksdb_column_family_handle_t,
64    pub(crate) multi_threaded_cfs: std::marker::PhantomData<&'a MultiThreaded>,
65}
66
67// internal struct which isn't exposed to public api.
68// but its memory will be exposed after transmute()-ing to BoundColumnFamily.
69// ColumnFamily's lifetime should be bound to DB. But, db holds cfs and cfs can't easily
70// self-reference DB as its lifetime due to rust's type system
71pub(crate) struct UnboundColumnFamily {
72    pub(crate) inner: *mut ffi::rocksdb_column_family_handle_t,
73}
74
75impl UnboundColumnFamily {
76    pub(crate) fn bound_column_family<'a>(self: Arc<Self>) -> Arc<BoundColumnFamily<'a>> {
77        // SAFETY: the new BoundColumnFamily here just adding lifetime,
78        // so that column family handle won't outlive db.
79        unsafe { Arc::from_raw(Arc::into_raw(self).cast()) }
80    }
81}
82
83fn destroy_handle(handle: *mut ffi::rocksdb_column_family_handle_t) {
84    // SAFETY: This should be called only from various Drop::drop(), strictly keeping a 1-to-1
85    // ownership to avoid double invocation to the rocksdb function with same handle.
86    unsafe {
87        ffi::rocksdb_column_family_handle_destroy(handle);
88    }
89}
90
91impl Drop for ColumnFamily {
92    fn drop(&mut self) {
93        destroy_handle(self.inner);
94    }
95}
96
97// these behaviors must be identical between BoundColumnFamily and UnboundColumnFamily
98// due to the unsafe transmute() in bound_column_family()!
99impl<'a> Drop for BoundColumnFamily<'a> {
100    fn drop(&mut self) {
101        destroy_handle(self.inner);
102    }
103}
104
105impl Drop for UnboundColumnFamily {
106    fn drop(&mut self) {
107        destroy_handle(self.inner);
108    }
109}
110
111/// Handy type alias to hide actual type difference to reference [`ColumnFamily`]
112/// depending on the `multi-threaded-cf` crate feature.
113#[cfg(not(feature = "multi-threaded-cf"))]
114pub type ColumnFamilyRef<'a> = &'a ColumnFamily;
115
116#[cfg(feature = "multi-threaded-cf")]
117pub type ColumnFamilyRef<'a> = Arc<BoundColumnFamily<'a>>;
118
119/// Utility trait to accept both supported references to `ColumnFamily`
120/// (`&ColumnFamily` and `BoundColumnFamily`)
121pub trait AsColumnFamilyRef {
122    fn inner(&self) -> *mut ffi::rocksdb_column_family_handle_t;
123}
124
125impl AsColumnFamilyRef for ColumnFamily {
126    fn inner(&self) -> *mut ffi::rocksdb_column_family_handle_t {
127        self.inner
128    }
129}
130
131impl<'a> AsColumnFamilyRef for &'a ColumnFamily {
132    fn inner(&self) -> *mut ffi::rocksdb_column_family_handle_t {
133        self.inner
134    }
135}
136
137// Only implement for Arc-ed BoundColumnFamily as this tightly coupled and
138// implementation detail, considering use of std::mem::transmute. BoundColumnFamily
139// isn't expected to be used as naked.
140// Also, ColumnFamilyRef might not be Arc<BoundColumnFamily<'a>> depending crate
141// feature flags so, we can't use the type alias here.
142impl<'a> AsColumnFamilyRef for Arc<BoundColumnFamily<'a>> {
143    fn inner(&self) -> *mut ffi::rocksdb_column_family_handle_t {
144        self.inner
145    }
146}
147
148unsafe impl Send for ColumnFamily {}
149unsafe impl Send for UnboundColumnFamily {}
150unsafe impl Sync for UnboundColumnFamily {}
151unsafe impl<'a> Send for BoundColumnFamily<'a> {}
rocksdb/column_family.rs

rocksdb/
column_family.rs
