aboutsummaryrefslogtreecommitdiff
path: root/src/storage.rs
diff options
context:
space:
mode:
Diffstat (limited to 'src/storage.rs')
-rw-r--r--src/storage.rs44
1 files changed, 44 insertions, 0 deletions
diff --git a/src/storage.rs b/src/storage.rs
index 51a418e..9e6b270 100644
--- a/src/storage.rs
+++ b/src/storage.rs
@@ -1,3 +1,9 @@
+//! Abstractions over different storage backends.
+//!
+//! The main trait to use here is [`Storage`], which provides the necessary interface to store
+//! tiles. Usually you want to have a `dyn Storage`, and then instantiate it with a concrete
+//! implementation (either [`Folder`] or [`Sqlite`]), depending on the command line flags or
+//! similar.
use color_eyre::{
eyre::{bail, WrapErr},
Result,
@@ -9,19 +15,40 @@ use std::{
path::{Path, PathBuf},
};
+/// The trait that provides the interface for storing tiles.
pub trait Storage {
+ /// Prepare the storage.
+ ///
+ /// This can be used to e.g. ensure the directory exists, or to create the database.
fn prepare(&mut self) -> Result<()>;
+ /// Prepare for a given zoom level.
+ ///
+ /// This function is called once per zoom, and can be used e.g. to set up the inner folder for
+ /// the level. This can avoid unnecesary syscalls if this setup would be done in
+ /// [`Storage::store`] instead.
fn prepare_zoom(&mut self, zoom: u32) -> Result<()>;
+ /// Store the given data for the tile.
fn store(&mut self, zoom: u32, x: u64, y: u64, data: &[u8]) -> Result<()>;
+ /// Finish the storing operation.
+ ///
+ /// This can flush any buffers, commit database changes, and so on.
fn finish(&mut self) -> Result<()>;
}
+/// Folder-based storage.
+///
+/// This stores the tiles according to the [slippy map
+/// tilenames](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).
#[derive(Debug)]
pub struct Folder {
base_dir: PathBuf,
}
impl Folder {
+ /// Create a new folder based storage.
+ ///
+ /// The given directory is the "root" directory, so a tile would be saved as
+ /// `base_dir/{zoom}/{x}/{y}.png`.
pub fn new(base_dir: PathBuf) -> Self {
Folder { base_dir }
}
@@ -70,12 +97,29 @@ impl Storage for Folder {
}
}
+/// SQLite based storage.
+///
+/// This stores tiles in a SQLite database. The database will have a single table:
+///
+/// ```sql
+/// CREATE TABLE tiles (
+/// zoom INTEGER,
+/// x INTEGER,
+/// y INTEGER,
+/// data BLOB,
+/// PRIMARY KEY (zoom, x, y)
+/// );
+/// ```
#[derive(Debug)]
pub struct Sqlite {
connection: Connection,
}
impl Sqlite {
+ /// Create a new SQLite backed tile store.
+ ///
+ /// The database will be saved at the given location. Note that the database must not yet
+ /// exist.
pub fn connect<P: AsRef<Path>>(file: P) -> Result<Self> {
let path = file.as_ref();
if fs::metadata(path).is_ok() {