From 45701f6b6ab1e46047efd502c016cfd3a3e662c3 Mon Sep 17 00:00:00 2001 From: wackbyte Date: Wed, 26 Jul 2023 06:00:16 -0400 Subject: [PATCH] Review grammar and spelling throughout the crate --- .rustme/docs.md | 8 ++++---- README.md | 12 ++++++------ benchmarks/benches/benchmarks.rs | 2 +- examples/basic.rs | 4 ++-- src/.crate-docs.md | 12 ++++++------ src/config.rs | 8 ++++---- src/entry.rs | 2 +- src/lib.rs | 6 +++--- src/log_file.rs | 12 ++++++------ src/manager.rs | 10 +++++----- 10 files changed, 38 insertions(+), 38 deletions(-) diff --git a/.rustme/docs.md b/.rustme/docs.md index b821767..61d4c2f 100644 --- a/.rustme/docs.md +++ b/.rustme/docs.md @@ -25,7 +25,7 @@ This crate exposes a WAL that supports: ## Basic How-To [`WriteAheadLog::recover()`]($wal-recover$) is used to create or recover a WAL -in a given directory. To open a log, an implementator of +in a given directory. To open a log, an implementer of [`LogManager`]($logmanager-trait$) must be provided. This trait is how OkayWAL communicates with your code when recovering or checkpointing a log. @@ -165,7 +165,7 @@ After this header, the file is a series of entries, each which contain a series of chunks. A byte with a value of 1 signifies a new entry. Any other byte causes the reader to stop reading entries from the file. -The first 8 bytes of the entry is the little-endian representation of its +The first 8 bytes of the entry are the little-endian representation of its `EntryId`. After the `EntryId`, a series of chunks is expected. A byte with a value of 2 @@ -174,10 +174,10 @@ this is the end of the current entry being written. Any other byte causes the `SegmentReader` to return an AbortedEntry result. Any already-read chunks from this entry should be ignored/rolled back by the `LogManager`. -The first four bytes of a chunk is the data length in little-endian +The first four bytes of a chunk are the data length in little-endian representation. The data for the chunk follows. -Finally, a four-byte crc32 ends the chunk. +Finally, a four-byte CRC-32 ends the chunk. If a reader does not encounter a new chunk marker (2) or an end-of-entry marker (3), the entry should be considered abandoned and all chunks should be ignored. diff --git a/README.md b/README.md index 2b1b3c0..7bd13f8 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ This crate exposes a WAL that supports: ## Basic How-To [`WriteAheadLog::recover()`](https://khonsulabs.github.io/okaywal/main/okaywal/struct.WriteAheadLog.html#method.recover) is used to create or recover a WAL -in a given directory. To open a log, an implementator of +in a given directory. To open a log, an implementer of [`LogManager`](https://khonsulabs.github.io/okaywal/main/okaywal/trait.LogManager.html) must be provided. This trait is how OkayWAL communicates with your code when recovering or checkpointing a log. @@ -35,7 +35,7 @@ The [basic example][basic-example] shows this process with many comments describing how OkayWAL works. ```rust,ignore -// Open a log using an Checkpointer that echoes the information passed into each +// Open a log using a Checkpointer that echoes the information passed into each // function that the Checkpointer trait defines. let log = WriteAheadLog::recover("my-log", LoggingCheckpointer)?; @@ -47,7 +47,7 @@ let mut writer = log.begin_entry()?; let record = writer.write_chunk("this is the first entry".as_bytes())?; // To fully flush all written bytes to disk and make the new entry -// resilliant to a crash, the writer must be committed. +// resilient to a crash, the writer must be committed. writer.commit()?; ``` @@ -180,7 +180,7 @@ After this header, the file is a series of entries, each which contain a series of chunks. A byte with a value of 1 signifies a new entry. Any other byte causes the reader to stop reading entries from the file. -The first 8 bytes of the entry is the little-endian representation of its +The first 8 bytes of the entry are the little-endian representation of its `EntryId`. After the `EntryId`, a series of chunks is expected. A byte with a value of 2 @@ -189,10 +189,10 @@ this is the end of the current entry being written. Any other byte causes the `SegmentReader` to return an AbortedEntry result. Any already-read chunks from this entry should be ignored/rolled back by the `LogManager`. -The first four bytes of a chunk is the data length in little-endian +The first four bytes of a chunk are the data length in little-endian representation. The data for the chunk follows. -Finally, a four-byte crc32 ends the chunk. +Finally, a four-byte CRC-32 ends the chunk. If a reader does not encounter a new chunk marker (2) or an end-of-entry marker (3), the entry should be considered abandoned and all chunks should be ignored. diff --git a/benchmarks/benches/benchmarks.rs b/benchmarks/benches/benchmarks.rs index b378254..57e8b2f 100644 --- a/benchmarks/benches/benchmarks.rs +++ b/benchmarks/benches/benchmarks.rs @@ -269,7 +269,7 @@ mod sqlite { // On macOS with built-in SQLite versions, despite the name and the SQLite // documentation, this pragma makes SQLite use `fcntl(_, F_BARRIER_FSYNC, // _)`. There's not a good practical way to make rusqlite's access of SQLite - // on macOS to use `F_FULLFSYNC`, which skews benchmarks heavily in favor of + // on macOS use `F_FULLFSYNC`, which skews benchmarks heavily in favor of // SQLite when not enabling this feature. // // Enabling this feature reduces the durability guarantees, which breaks diff --git a/examples/basic.rs b/examples/basic.rs index 264da57..c2d3876 100644 --- a/examples/basic.rs +++ b/examples/basic.rs @@ -4,7 +4,7 @@ use okaywal::{Entry, EntryId, LogManager, SegmentReader, WriteAheadLog}; fn main() -> io::Result<()> { // begin rustme snippet: readme-example - // Open a log using an Checkpointer that echoes the information passed into each + // Open a log using a Checkpointer that echoes the information passed into each // function that the Checkpointer trait defines. let log = WriteAheadLog::recover("my-log", LoggingCheckpointer)?; @@ -16,7 +16,7 @@ fn main() -> io::Result<()> { let record = writer.write_chunk("this is the first entry".as_bytes())?; // To fully flush all written bytes to disk and make the new entry - // resilliant to a crash, the writer must be committed. + // resilient to a crash, the writer must be committed. writer.commit()?; // end rustme snippet diff --git a/src/.crate-docs.md b/src/.crate-docs.md index 1599603..5d55d22 100644 --- a/src/.crate-docs.md +++ b/src/.crate-docs.md @@ -25,7 +25,7 @@ This crate exposes a WAL that supports: ## Basic How-To [`WriteAheadLog::recover()`](WriteAheadLog::recover) is used to create or recover a WAL -in a given directory. To open a log, an implementator of +in a given directory. To open a log, an implementer of [`LogManager`](LogManager) must be provided. This trait is how OkayWAL communicates with your code when recovering or checkpointing a log. @@ -33,7 +33,7 @@ The [basic example][basic-example] shows this process with many comments describing how OkayWAL works. ```rust,ignore -// Open a log using an Checkpointer that echoes the information passed into each +// Open a log using a Checkpointer that echoes the information passed into each // function that the Checkpointer trait defines. let log = WriteAheadLog::recover("my-log", LoggingCheckpointer)?; @@ -45,7 +45,7 @@ let mut writer = log.begin_entry()?; let record = writer.write_chunk("this is the first entry".as_bytes())?; // To fully flush all written bytes to disk and make the new entry -// resilliant to a crash, the writer must be committed. +// resilient to a crash, the writer must be committed. writer.commit()?; ``` @@ -178,7 +178,7 @@ After this header, the file is a series of entries, each which contain a series of chunks. A byte with a value of 1 signifies a new entry. Any other byte causes the reader to stop reading entries from the file. -The first 8 bytes of the entry is the little-endian representation of its +The first 8 bytes of the entry are the little-endian representation of its `EntryId`. After the `EntryId`, a series of chunks is expected. A byte with a value of 2 @@ -187,10 +187,10 @@ this is the end of the current entry being written. Any other byte causes the `SegmentReader` to return an AbortedEntry result. Any already-read chunks from this entry should be ignored/rolled back by the `LogManager`. -The first four bytes of a chunk is the data length in little-endian +The first four bytes of a chunk are the data length in little-endian representation. The data for the chunk follows. -Finally, a four-byte crc32 ends the chunk. +Finally, a four-byte CRC-32 ends the chunk. If a reader does not encounter a new chunk marker (2) or an end-of-entry marker (3), the entry should be considered abandoned and all chunks should be ignored. diff --git a/src/config.rs b/src/config.rs index a208626..e46ba7c 100644 --- a/src/config.rs +++ b/src/config.rs @@ -74,7 +74,7 @@ where version_info: Arc::default(), } } - /// Sets the number of bytes to preallocate for each segment file. Returns self. + /// Sets the number of bytes to preallocate for each segment file. Returns `self`. /// /// Preallocating disk space allows for more consistent performance. This /// number should be large enough to allow batching multiple entries into @@ -85,9 +85,9 @@ where } /// Sets the number of bytes written required to begin a checkpoint - /// operation. Returns self. + /// operation. Returns `self`. /// - /// This value should be smaller than `preallocate_bytes` tp ensure + /// This value should be smaller than `preallocate_bytes` to ensure /// checkpoint operations begin before too much data is written in a log /// entry. If more data is written before a checkpoint occurs, the segment /// will grow to accomodate the extra data, but that write will not be as @@ -99,7 +99,7 @@ where } /// Sets the number of bytes to use for internal buffers when reading and - /// writing data to the log. + /// writing data to the log. Returns `self`. pub fn buffer_bytes(mut self, bytes: usize) -> Self { self.buffer_bytes = bytes; self diff --git a/src/entry.rs b/src/entry.rs index 050bc51..bf783de 100644 --- a/src/entry.rs +++ b/src/entry.rs @@ -284,7 +284,7 @@ fn log_position_serialization() { pub struct ChunkRecord { /// The position of the chunk. pub position: LogPosition, - /// The crc calculated for the chunk. + /// The CRC calculated for the chunk. pub crc: u32, /// The length of the data contained inside of the chunk. pub length: u32, diff --git a/src/lib.rs b/src/lib.rs index 930122a..6f29dfe 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -448,7 +448,7 @@ where /// /// This call will not interrupt any writers, and will block indefinitely if /// another instance of this [`WriteAheadLog`] exists and is not eventually - /// dropped. This was is the safest to implement, and because a WAL is + /// dropped. This was the safest to implement, and because a WAL is /// primarily used in front of another storage layer, it follows that the /// shutdown logic of both layers should be synchronized. pub fn shutdown(self) -> io::Result<()> { @@ -588,8 +588,8 @@ where if self.bytes_remaining == 0 { if self.stored_crc32.is_none() { let mut stored_crc32 = [0; 4]; - // Bypass our internal read, otherwise our crc would include the - // crc read itself. + // Bypass our internal read, otherwise our CRC would include the + // CRC read itself. self.reader.read_exact(&mut stored_crc32)?; self.stored_crc32 = Some(u32::from_le_bytes(stored_crc32)); } diff --git a/src/log_file.rs b/src/log_file.rs index 131e3a9..f4fb9e4 100644 --- a/src/log_file.rs +++ b/src/log_file.rs @@ -487,7 +487,7 @@ where /// Reads all chunks for this entry. If the entry was completely written, /// the list of chunks of data is returned. If the entry wasn't completely - /// written, None will be returned. + /// written, `None` will be returned. pub fn read_all_chunks(&mut self) -> io::Result>>> { let mut chunks = Vec::new(); loop { @@ -518,7 +518,7 @@ where /// An aborted entry was detected. This should only be encountered if log /// entries were being written when the computer or application crashed. /// - /// When is returned, the entire entry should be ignored. + /// When this is returned, the entire entry should be ignored. AbortedEntry, } @@ -566,15 +566,15 @@ where self.bytes_remaining } - /// Returns true if the CRC has been validated, or false if the computed crc - /// is different than the stored crc. Returns an error if the chunk has not + /// Returns true if the CRC has been validated, or false if the computed CRC + /// is different than the stored CRC. Returns an error if the chunk has not /// been fully read yet. pub fn check_crc(&mut self) -> io::Result { if self.bytes_remaining == 0 { if self.stored_crc32.is_none() { let mut stored_crc32 = [0; 4]; - // Bypass our internal read, otherwise our crc would include the - // crc read itself. + // Bypass our internal read, otherwise our CRC would include the + // CRC read itself. self.entry.reader.file.read_exact(&mut stored_crc32)?; self.stored_crc32 = Some(u32::from_le_bytes(stored_crc32)); } diff --git a/src/manager.rs b/src/manager.rs index 8602e0f..a98c1a0 100644 --- a/src/manager.rs +++ b/src/manager.rs @@ -40,11 +40,11 @@ where /// `checkpointed_entries` can be used to iterate over all entries that are /// being checkpointed. /// - /// Shortly after function returns, the entries stored within the file being - /// checkpointed will no longer be accessible. To ensure ACID compliance of - /// the underlying storage layer, all necessary changes must be fully - /// synchronized to the underlying storage medium before this function call - /// returns. + /// Shortly after this function returns, the entries stored within the file + /// being checkpointed will no longer be accessible. To ensure ACID + /// compliance of the underlying storage layer, all necessary changes must + /// be fully synchronized to the underlying storage medium before this + /// function returns. fn checkpoint_to( &mut self, last_checkpointed_id: EntryId,