Prepare 0.4.0

- Add unsafe functions for turning entry references into pointers. - Add `source` to `LockingError::WouldBlock` - Add `ContiguousMemoryStorage::forget` utility method. - Rename `ContiguousMemoryStorage::store` to `push` so it's more in line with std containers. - Update examples - Rename `ContiguousMemoryRef` to `ContiguousEntryRef` so naming is more in line with the purpose of the struct. - Clean up `ByteRange::aligned` implementation - Fix how `AllocationTracker` provides available `ByteRange`s so they're properly aligned. - Remove `StoreData` trait as it wasn't supposed to be used. - Remove `ContiguousMemoryStorage` trait as it only complicated implementation. - Remove deprecated re-exports. - Add semver checking workflow - Simplify CI workflow Signed-off-by: Tin Svagelj <[email protected]>
Caellian · Sep 15, 2023 · 7a11487 · 7a11487
1 parent 4362153
commit 7a11487
Show file tree

Hide file tree

Showing 18 changed files with 779 additions and 306 deletions.
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
@@ -16,15 +16,9 @@ jobs:
       - run: rustup update nightly && rustup default nightly
       - name: Build default
         run: cargo build --verbose
-      - name: Build no_std
-        run: cargo build --verbose --no-default-features --features no_std
-      - name: Build no_std with error_in_core
-        run: cargo build --verbose --no-default-features --features no_std,error_in_core
-      - name: Build with ptr_metadata
-        run: cargo build --verbose --features ptr_metadata
-      - name: Build restrictive
-        run: cargo build --verbose --no-default-features --features std
+      - name: Build no_std all features
+        run: cargo build --verbose --no-default-features --features no_std,debug,ptr_metadata,error_in_core
       - name: Build all features
-        run: cargo build --verbose --all-features
+        run: cargo build --verbose --no-default-features --features std,debug,ptr_metadata,error_in_core
       - name: Run tests
         run: cargo test --verbose --features ptr_metadata
diff --git a/.github/workflows/semver.yml b/.github/workflows/semver.yml
@@ -0,0 +1,19 @@
+name: Rust
+
+on:
+  push:
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - run: rustup update nightly && rustup default nightly
+      - run: cargo install cargo-semver-checks
+      - name: Run semver check
+        run: cargo semver-checks check-release
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -97,6 +97,43 @@
             "args": [],
             "cwd": "${workspaceFolder}"
         },
+        {
+            "type": "lldb",
+            "request": "launch",
+            "name": "Debug example 'game_loading'",
+            "cargo": {
+                "args": [
+                    "build",
+                    "--example=game_loading",
+                    "--package=contiguous-mem"
+                ],
+                "filter": {
+                    "name": "game_loading",
+                    "kind": "example"
+                }
+            },
+            "args": [],
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "type": "lldb",
+            "request": "launch",
+            "name": "Debug unit tests in example 'game_loading'",
+            "cargo": {
+                "args": [
+                    "test",
+                    "--no-run",
+                    "--example=game_loading",
+                    "--package=contiguous-mem"
+                ],
+                "filter": {
+                    "name": "game_loading",
+                    "kind": "example"
+                }
+            },
+            "args": [],
+            "cwd": "${workspaceFolder}"
+        },
         {
             "type": "lldb",
             "request": "launch",

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "contiguous-mem"
-version = "0.3.1"
+version = "0.4.0"
 edition = "2021"
 description = "A contiguous memory storage"
 authors = ["Tin Švagelj <[email protected]>"]
@@ -19,13 +19,16 @@ portable-atomic = { version = "1", default-features = false, optional = true }
 spin = { version = "0.9", optional = true }
 
 [features]
-default = ["std", "leak_data"]
+default = ["std", "ptr_metadata"]
 std = []
 no_std = ["dep:portable-atomic", "dep:spin"]
 debug = []
 leak_data = []
 ptr_metadata = []
 error_in_core = []
 
+[dev-dependencies]
+byteorder = "1.4"
+
 [package.metadata.docs.rs]
 all-features = true
diff --git a/README.md b/README.md
@@ -1,11 +1,21 @@
 # contiguous_mem
 
 contiguous_mem streamlines storage and management of data stored in contiguous
-memory block.
+blocks of memory.
 
-[![CI](https://github.com/Caellian/contiguous_mem/actions/workflows/rust.yml/badge.svg)](https://github.com/Caellian/contiguous_mem/actions/workflows/rust.yml)
-[![Crates.io](https://img.shields.io/crates/v/contiguous_mem)](https://crates.io/crates/contiguous_mem)
-[![Documentation](https://docs.rs/contiguous_mem/badge.svg)](https://docs.rs/contiguous_mem)
+[![Crate](https://img.shields.io/crates/v/contiguous_mem?style=for-the-badge&logo=docs.rs)](https://crates.io/crates/contiguous_mem)
+[![Documentation](https://img.shields.io/docsrs/contiguous-mem?style=for-the-badge&logo=rust)](https://docs.rs/contiguous-mem)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/Caellian/contiguous_mem/rust.yml?style=for-the-badge&logo=githubactions&logoColor=%23fff&label=CI)](https://github.com/Caellian/contiguous_mem/actions/workflows/rust.yml)
+[![Zlib or MIT or Apache 2.0 license](https://img.shields.io/crates/l/contiguous-mem?style=for-the-badge)](https://github.com/Caellian/contiguous_mem#license)
+
+## Stability
+
+All versions prior to 1.0.0 are not considered production ready. This is my
+first crate and there's still a lot of edge cases I didn't get a chance to
+consider yet.
+
+Prelimenary tests are in place but I don't consider them sufficient to guarantee
+correctness of behavior.
 
 ## Key Features
 
@@ -23,33 +33,33 @@ safely wrapping referenced data if you don't need it.
 Default implementation keeps relative offsets of stored data which are resolved
 on access.
 
-## Tradeoffs
+## Use cases
 
-- Works without nightly but leaks data, enable `ptr_metadata` or disable default
-  `leak_data` feature flag if memory leaks are an issue:
+- Ensuring stored data is placed adjacently in memory. ([example](./examples/game_loading.rs))
+- Storing differently typed/sized data. ([example](./examples/default_impl.rs))
 
+## Tradeoffs
+
+- Works without nightly but leaks data requiring Drop or drop glue, enable
+  `ptr_metadata` or disable default `leak_data` feature flag if memory leaks are
+  an issue:
   - `ptr_metadata` requires nightly,
   - disabling `leak_data` imposes `Copy` requirement on stored types.
 
-- References returned by `store` function follow the same borrow restrictions as the
-  language, `Deref` is implemented for `ContiguousMemoryRef` but it will panic on
-  dereference if it's been already mutably borrowed somewhere else.
-  Use `ContiguousMemoryRef::try_get` if you'd like to handle that properly.
-
 ## Getting Started
 
 Add the crate to your dependencies:
 
 ```toml
 [dependencies]
-contiguous_mem = { version = "0.3.0" }
+contiguous_mem = { version = "0.4.*" }
 ```
 
 Optionally disable the `std` feature and enable `no_std` feature to use in `no_std` environment:
 
 ```toml
 [dependencies]
-contiguous_mem = { version = "0.3.0", default-features = false, features = ["no_std"] }
+contiguous_mem = { version = "0.4.*", default-features = false, features = ["no_std"] }
 ```
 
 ### Features
@@ -59,10 +69,13 @@ contiguous_mem = { version = "0.3.0", default-features = false, features = ["no_
 - `leak_data` (**default**) - disables `Copy` requirement for stored types, but any
   references in stored data will be leaked when the memory container is dropped
 - `debug` - enables `derive(Debug)` on structures unrelated to error handling
-- `ptr_metadata` &lt;_nightly_&gt; - enables support for casting returned references
-  into `dyn Trait` types as well as cleaning up any types that implement `Drop`
-  or generate drop glue
-- `error_in_core` &lt;_nightly_&gt; - enables support for `core::error::Error` in `no_std` environment
+- [`ptr_metadata`](https://doc.rust-lang.org/beta/unstable-book/library-features/ptr-metadata.html)
+  &lt;_nightly_&gt; - enables support for casting returned references into
+  `dyn Trait` types as well as cleaning up any types that implement `Drop` or
+  generate drop glue
+- [`error_in_core`](https://dev-doc.rust-lang.org/stable/unstable-book/library-features/error-in-core.html)
+  &lt;_nightly_&gt; - enables support for `core::error::Error` in `no_std`
+  environment
 
 ### Usage
 
@@ -80,18 +93,34 @@ fn main() {
 
     // Store data in the memory container
     let data = Data { value: 42 };
-    let stored_number: ContiguousMemoryRef<u64> = memory.store(22u64);
-    let stored_data: ContiguousMemoryRef<Data> = memory.store(data);
+    let stored_number: ContiguousMemoryRef<u64> = memory.push(22u64);
+    let stored_data: ContiguousMemoryRef<Data> = memory.push(data);
 
     // Retrieve and use the stored data
     assert_eq!(*stored_data.get(), data);
     assert_eq!(*stored_number.get(), 22);
 }
 ```
 
+- References have a similar API as
+  [`RefCell`](https://doc.rust-lang.org/stable/std/cell/struct.RefCell.html)
+
 <cite>Note that reference types returned by store are inferred and only shown
 here for demonstration purposes.</cite>
 
+## Alternatives
+
+- manually managing memory to ensure contiguous placement of data
+  - prone to errors and requires unsafe code
+- using a custom allocator like
+  [blink-alloc](https://crates.io/crates/blink-alloc) to ensure contiguous
+  placement of data
+  - requires [`allocator_api`](https://doc.rust-lang.org/beta/unstable-book/library-features/allocator-api.html)
+    feature
+  - `blink-alloc` provides a similar functionality as this crate without the
+    `allocator_api` feature; intended for use in loops so it doesn't support
+    freeing _some_ values while retaining other
+
 ## Contributions
 
 Contributions are welcome, feel free to

diff --git a/doc/crate.md b/doc/crate.md
@@ -20,10 +20,13 @@ See individual items for usage examples.
 - `leak_data` (**default**) - disables `Copy` requirement for stored types, but any
   references in stored data will be leaked when the memory container is dropped
 - `debug` - enables `derive(Debug)` on structures unrelated to error handling
-- `ptr_metadata` &lt;_nightly_&gt; - enables support for casting returned references
-  into `dyn Trait` types as well as cleaning up any types that implement `Drop`
-  or generate drop glue
-- `error_in_core` &lt;_nightly_&gt; - enables support for `core::error::Error` in `no_std` environment
+- [`ptr_metadata`](https://doc.rust-lang.org/beta/unstable-book/library-features/ptr-metadata.html)
+  &lt;_nightly_&gt; - enables support for casting returned references into
+  `dyn Trait` types as well as cleaning up any types that implement `Drop` or
+  generate drop glue
+- [`error_in_core`](https://dev-doc.rust-lang.org/stable/unstable-book/library-features/error-in-core.html)
+  &lt;_nightly_&gt; - enables support for `core::error::Error` in `no_std`
+  environment
 
 ## Contributions
 

diff --git a/examples/default_impl.rs b/examples/default_impl.rs
@@ -11,8 +11,8 @@ fn main() {
 
     // Store data in the memory container
     let data = Data { value: 42 };
-    let stored_number: ContiguousMemoryRef<u64> = memory.store(22u64);
-    let stored_data: ContiguousMemoryRef<Data> = memory.store(data);
+    let stored_number: ContiguousEntryRef<u64> = memory.push(22u64);
+    let stored_data: ContiguousEntryRef<Data> = memory.push(data);
 
     // Retrieve and use the stored data
     assert_eq!(*stored_data.get(), data);