Skip to content

Commit

Permalink
queue-ser: changes for 0.1.0 release
Browse files Browse the repository at this point in the history
Added changelog, initial readme, and Cargo.toml updates for the
initial release of virtio-queue-ser.

Signed-off-by: Alexandru Agache <aagch@amazon.com>
  • Loading branch information
alexandruag authored and andreeaflorescu committed May 13, 2022
1 parent 47cabf8 commit fd17757
Show file tree
Hide file tree
Showing 3 changed files with 34 additions and 1 deletion.
3 changes: 3 additions & 0 deletions crates/virtio-queue-ser/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# v0.1.0

This is the first release of the crate, compatible with version `0.3.x` of `virtio-queue`.
3 changes: 2 additions & 1 deletion crates/virtio-queue-ser/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,6 @@ edition = "2018"
serde = { version = ">=1.0.27", features = ["derive"] }
versionize = ">=0.1.6"
versionize_derive = ">=0.1.3"
virtio-queue = { path = "../../crates/virtio-queue" }
# The `path` part gets stripped when publishing the crate.
virtio-queue = { path = "../../crates/virtio-queue", version = "^0.3.0" }
vm-memory = ">=0.8.0"
29 changes: 29 additions & 0 deletions crates/virtio-queue-ser/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# virtio-queue-ser

This crate is a companion to [virtio-queue](https://crates.io/crates/virtio-queue),
focusing on persistent state representation for use cases such as (de)serialization.
The main abstraction is the `QueueStateSer` object, which can be converted to and
from `QueueState` via the provided `From` trait implementations. `virtio-queue-ser` currently
supports (de)serialization of `QueueStateSer` objects via [serde](https://crates.io/crates/serde)
and [versionize](https://crates.io/crates/versionize). The former always serializes the latest
version of `QueueStateSer`, whereas multiple versions will be supported with `versionize` as
breaking changes are introduced to `QueueState` (and, by extension, `QueueStateSer`).

On serialization, the typical workflow is to start from a `state: QueueState` object, obtain
the corresponding `QueueStateSer` (i.e. `state_ser = QueueStateSer::from(&state)`), then write
the serialized data using the underlying backend (i.e. `serde` or `versionize`). When deserializing,
we first get a `state_ser: QueueStateSer` object from the backend, and then convert it to a
`QueueState` (for example, `state = QueueState::from(&state_ser)`).

When a `versionize`-based backend is used, the state transformations required to transition between
versions are transparent to consumers of `virtio-queue-ser`. For example, if an older version of
`QueueStateSer` has been serialized with `versionize`, and we're deserializing based on that data,
then the `QueueStateSer` object obtained via `versionize` will automatically include any changes
required for converting to the current version.

## License

This project is licensed under either of

- [Apache License](http://www.apache.org/licenses/LICENSE-2.0), Version 2.0
- [BSD-3-Clause License](https://opensource.org/licenses/BSD-3-Clause)

0 comments on commit fd17757

Please sign in to comment.