From 3542ebb2bc792428ccbdfbe0e90ed67e48b63785 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sat, 30 Sep 2023 09:46:45 -0700 Subject: [PATCH 01/14] export `LocationSet` under the `core` module --- chorus_book/src/guide-projector.md | 6 ++---- chorus_book/src/guide-transport.md | 14 +++++--------- chorus_book/src/header.txt | 3 +-- chorus_lib/examples/bookseller.rs | 3 +-- chorus_lib/examples/bookseller2.rs | 3 +-- chorus_lib/examples/hello.rs | 3 +-- chorus_lib/examples/input-output.rs | 5 +---- chorus_lib/examples/loc-poly.rs | 3 +-- chorus_lib/examples/runner.rs | 5 ++--- chorus_lib/examples/tic-tac-toe.rs | 4 ++-- chorus_lib/src/core.rs | 27 +++++++++++++++++++++++---- chorus_lib/src/transport.rs | 3 +-- chorus_lib/src/transport/local.rs | 4 +--- 13 files changed, 42 insertions(+), 41 deletions(-) diff --git a/chorus_book/src/guide-projector.md b/chorus_book/src/guide-projector.md index 0a84c40..5378a8b 100644 --- a/chorus_book/src/guide-projector.md +++ b/chorus_book/src/guide-projector.md @@ -9,8 +9,7 @@ To create a `Projector`, you need to provide the target location and the transpo ```rust # extern crate chorus_lib; # use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; -# use chorus_lib::core::{ChoreographyLocation, Projector}; -# use chorus_lib::{LocationSet}; +# use chorus_lib::core::{ChoreographyLocation, Projector, LocationSet}; # let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); # let alice_transport = LocalTransport::new(Alice, transport_channel.clone()); # #[derive(ChoreographyLocation)] @@ -29,8 +28,7 @@ To execute a choreography, you need to call the `epp_and_run` method on the `Pro ```rust # extern crate chorus_lib; # use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; -# use chorus_lib::core::{ChoreographyLocation, Projector, Choreography, ChoreoOp}; -# use chorus_lib::{LocationSet}; +# use chorus_lib::core::{ChoreographyLocation, Projector, Choreography, ChoreoOp, LocationSet}; # let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); # let alice_transport = LocalTransport::new(Alice, transport_channel.clone()); # #[derive(ChoreographyLocation)] diff --git a/chorus_book/src/guide-transport.md b/chorus_book/src/guide-transport.md index 504030e..56f99db 100644 --- a/chorus_book/src/guide-transport.md +++ b/chorus_book/src/guide-transport.md @@ -12,8 +12,7 @@ The `local` transport is used to execute choreographies on the same machine on d ```rust # extern crate chorus_lib; -# use chorus_lib::core::{ChoreographyLocation}; -# use chorus_lib::{LocationSet}; +# use chorus_lib::core::{ChoreographyLocation, LocationSet}; # #[derive(ChoreographyLocation)] # struct Alice; # #[derive(ChoreographyLocation)] @@ -24,13 +23,12 @@ let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); ``` To use the `local` transport, first import the `LocalTransport` struct from the `chorus_lib` crate. - + Then build the transport by using the `LocalTransport::new` associated function, which takes a target location (explained in the [Projector section](./guide-projector.md)) and the `LocalTransportChannel`. ```rust # extern crate chorus_lib; -# use chorus_lib::core::{ChoreographyLocation}; -# use chorus_lib::{LocationSet}; +# use chorus_lib::core::{ChoreographyLocation, LocationSet}; # #[derive(ChoreographyLocation)] # struct Alice; # use chorus_lib::transport::local::LocalTransportChannel; @@ -46,8 +44,7 @@ Because of the nature of the `Local` transport, you must use the same `LocalTran # extern crate chorus_lib; # use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; # use std::thread; -# use chorus_lib::core::{ChoreographyLocation, ChoreoOp, Choreography, Projector}; -# use chorus_lib::{LocationSet}; +# use chorus_lib::core::{ChoreographyLocation, ChoreoOp, Choreography, Projector, LocationSet}; # #[derive(ChoreographyLocation)] # struct Alice; # #[derive(ChoreographyLocation)] @@ -116,10 +113,9 @@ let config = TransportConfig::for_target(Alice, ()) See the API documentation for more details. - ### Note on the location set of the Choreography -Note that when calling `epp_and_run` on a `Projector`, you will get a compile error if the location set of the `Choreography` is not a subset of the location set of the `Transport`. In other words, the `Transport` should have information about every `ChoreographyLocation` that `Choreography` can talk about. So this will fail: +Note that when calling `epp_and_run` on a `Projector`, you will get a compile error if the location set of the `Choreography` is not a subset of the location set of the `Transport`. In other words, the `Transport` should have information about every `ChoreographyLocation` that `Choreography` can talk about. So this will fail: ```rust, compile_fail # extern crate chorus_lib; diff --git a/chorus_book/src/header.txt b/chorus_book/src/header.txt index 7231c30..d22111b 100644 --- a/chorus_book/src/header.txt +++ b/chorus_book/src/header.txt @@ -1,7 +1,6 @@ # extern crate chorus_lib; -# use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, Projector, Located, Superposition, Runner}; +# use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, Projector, Located, Superposition, Runner, LocationSet}; # use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; -# use chorus_lib::{LocationSet}; # #[derive(ChoreographyLocation)] # struct Alice; # #[derive(ChoreographyLocation)] diff --git a/chorus_lib/examples/bookseller.rs b/chorus_lib/examples/bookseller.rs index 7889aa6..61152ea 100644 --- a/chorus_lib/examples/bookseller.rs +++ b/chorus_lib/examples/bookseller.rs @@ -5,9 +5,8 @@ use std::thread; use chrono::NaiveDate; -use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, Projector}; +use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, LocationSet, Projector}; use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; -use chorus_lib::LocationSet; fn get_book(title: &str) -> Option<(i32, NaiveDate)> { match title.trim() { diff --git a/chorus_lib/examples/bookseller2.rs b/chorus_lib/examples/bookseller2.rs index 729d5af..e493af6 100644 --- a/chorus_lib/examples/bookseller2.rs +++ b/chorus_lib/examples/bookseller2.rs @@ -4,9 +4,8 @@ use std::collections::HashMap; use std::sync::Arc; use std::thread; -use chorus_lib::LocationSet; use chorus_lib::{ - core::{ChoreoOp, Choreography, ChoreographyLocation, Located, Projector}, + core::{ChoreoOp, Choreography, ChoreographyLocation, Located, LocationSet, Projector}, transport::local::{LocalTransport, LocalTransportChannel}, }; use chrono::NaiveDate; diff --git a/chorus_lib/examples/hello.rs b/chorus_lib/examples/hello.rs index ba8bcfd..f11f242 100644 --- a/chorus_lib/examples/hello.rs +++ b/chorus_lib/examples/hello.rs @@ -2,9 +2,8 @@ extern crate chorus_lib; use std::thread; -use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, Projector}; +use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, LocationSet, Projector}; use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; -use chorus_lib::LocationSet; // --- Define two locations (Alice and Bob) --- diff --git a/chorus_lib/examples/input-output.rs b/chorus_lib/examples/input-output.rs index a02844b..7664a65 100644 --- a/chorus_lib/examples/input-output.rs +++ b/chorus_lib/examples/input-output.rs @@ -1,8 +1,5 @@ extern crate chorus_lib; -use chorus_lib::{ - core::{ChoreoOp, Choreography, ChoreographyLocation, Located}, - LocationSet, -}; +use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, Located, LocationSet}; #[derive(ChoreographyLocation)] struct Alice; #[derive(ChoreographyLocation)] diff --git a/chorus_lib/examples/loc-poly.rs b/chorus_lib/examples/loc-poly.rs index e6b8e0b..f2a50d5 100644 --- a/chorus_lib/examples/loc-poly.rs +++ b/chorus_lib/examples/loc-poly.rs @@ -3,10 +3,9 @@ use std::fmt::Debug; use std::thread; use chorus_lib::core::{ - ChoreoOp, Choreography, ChoreographyLocation, Located, Portable, Projector, + ChoreoOp, Choreography, ChoreographyLocation, Located, LocationSet, Portable, Projector, }; use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; -use chorus_lib::LocationSet; #[derive(ChoreographyLocation)] struct Alice; diff --git a/chorus_lib/examples/runner.rs b/chorus_lib/examples/runner.rs index 83dd4a7..e6d39ec 100644 --- a/chorus_lib/examples/runner.rs +++ b/chorus_lib/examples/runner.rs @@ -1,7 +1,6 @@ extern crate chorus_lib; -use chorus_lib::{ - core::{ChoreoOp, Choreography, ChoreographyLocation, Located, Runner, Superposition}, - LocationSet, +use chorus_lib::core::{ + ChoreoOp, Choreography, ChoreographyLocation, Located, LocationSet, Runner, Superposition, }; #[derive(ChoreographyLocation)] diff --git a/chorus_lib/examples/tic-tac-toe.rs b/chorus_lib/examples/tic-tac-toe.rs index 79abb03..6a09302 100644 --- a/chorus_lib/examples/tic-tac-toe.rs +++ b/chorus_lib/examples/tic-tac-toe.rs @@ -4,10 +4,10 @@ extern crate chorus_lib; use chorus_lib::transport::http::HttpTransportConfig; use chorus_lib::{ core::{ - ChoreoOp, Choreography, ChoreographyLocation, Deserialize, Located, Projector, Serialize, + ChoreoOp, Choreography, ChoreographyLocation, Deserialize, Located, LocationSet, Projector, + Serialize, }, transport::http::HttpTransport, - LocationSet, }; use clap::Parser; diff --git a/chorus_lib/src/core.rs b/chorus_lib/src/core.rs index f2ba43e..00809d6 100644 --- a/chorus_lib/src/core.rs +++ b/chorus_lib/src/core.rs @@ -120,16 +120,35 @@ where } } -// TODO(shumbo): Export the macro under the `core` module +// To export `LocationSet` under the `core` module, we define an internal macro and export it. +// This is because Rust does not allow us to export a macro from a module without re-exporting it. +// `__ChoRus_Internal_LocationSet` is the internal macro and it is configured not to be visible in the documentation. -/// Macro to generate hlist +/// Macro to define a set of locations that a choreography is defined on. +/// +/// ``` +/// # use chorus_lib::core::{ChoreographyLocation, LocationSet}; +/// # +/// # #[derive(ChoreographyLocation)] +/// # struct Alice; +/// # #[derive(ChoreographyLocation)] +/// # struct Bob; +/// # #[derive(ChoreographyLocation)] +/// # struct Carol; +/// # +/// type L = LocationSet!(Alice, Bob, Carol); +/// ``` +#[doc(hidden)] #[macro_export] -macro_rules! LocationSet { +macro_rules! __ChoRus_Internal_LocationSet { () => { $crate::core::HNil }; ($head:ty $(,)*) => { $crate::core::HCons<$head, $crate::core::HNil> }; - ($head:ty, $($tail:tt)*) => { $crate::core::HCons<$head, $crate::LocationSet!($($tail)*)> }; + ($head:ty, $($tail:tt)*) => { $crate::core::HCons<$head, $crate::core::LocationSet!($($tail)*)> }; } +#[doc(inline)] +pub use __ChoRus_Internal_LocationSet as LocationSet; + /// Marker pub struct Here; /// Marker diff --git a/chorus_lib/src/transport.rs b/chorus_lib/src/transport.rs index 9f8209a..6d98d8c 100644 --- a/chorus_lib/src/transport.rs +++ b/chorus_lib/src/transport.rs @@ -3,8 +3,7 @@ pub mod http; pub mod local; -use crate::core::{ChoreographyLocation, HCons, HList}; -use crate::LocationSet; +use crate::core::{ChoreographyLocation, HCons, HList, LocationSet}; use std::collections::HashMap; use std::marker::PhantomData; diff --git a/chorus_lib/src/transport/local.rs b/chorus_lib/src/transport/local.rs index 3ba58b3..6533467 100644 --- a/chorus_lib/src/transport/local.rs +++ b/chorus_lib/src/transport/local.rs @@ -7,9 +7,7 @@ use serde_json; use std::marker::PhantomData; -use crate::LocationSet; - -use crate::core::{ChoreographyLocation, HCons, HList, Portable, Transport}; +use crate::core::{ChoreographyLocation, HCons, HList, LocationSet, Portable, Transport}; use crate::utils::queue::BlockingQueue; type QueueMap = HashMap>>; From be86cb3b1d9262f44ce04c8348b1dd03f9f5a3d9 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sat, 30 Sep 2023 09:56:55 -0700 Subject: [PATCH 02/14] hide internal structures from the documentation --- chorus_lib/src/core.rs | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/chorus_lib/src/core.rs b/chorus_lib/src/core.rs index 00809d6..2c43e92 100644 --- a/chorus_lib/src/core.rs +++ b/chorus_lib/src/core.rs @@ -6,6 +6,7 @@ use std::marker::PhantomData; use serde::de::DeserializeOwned; // re-export so that users can use derive macros without importing serde +#[doc(no_inline)] pub use serde::{Deserialize, Serialize}; /// Represents a location. It can be derived using `#[derive(ChoreographyLocation)]`. @@ -92,15 +93,18 @@ where // --- HList and Helpers --- /// heterogeneous list +#[doc(hidden)] pub trait HList { /// returns fn to_string_list() -> Vec<&'static str>; } /// end of HList +#[doc(hidden)] pub struct HNil; /// An element of HList +#[doc(hidden)] pub struct HCons(Head, Tail); impl HList for HNil { @@ -150,13 +154,20 @@ macro_rules! __ChoRus_Internal_LocationSet { pub use __ChoRus_Internal_LocationSet as LocationSet; /// Marker +#[doc(hidden)] pub struct Here; /// Marker +#[doc(hidden)] pub struct There(Index); -/// Check membership +/// Check if a location is a member of a location set +/// +/// The trait is used to check if a location is a member of a location set. +/// +/// It takes two type parameters `L` and `Index`. `L` is a location set and `Index` is some type that is inferred by the compiler. +/// If a location `L1` is in `L`, then there exists a type `Index` such that `L1` implements `Member`. pub trait Member { - /// Return HList of non-member + /// A location set that is the remainder of `L` after removing the member. type Remainder: HList; } @@ -175,7 +186,12 @@ where type Remainder = HCons; } -/// Check subset +/// Check if a location set is a subset of another location set +/// +/// The trait is used to check if a location set is a subset of another location set. +/// +/// It takes two type parameters `L` and `Index`. `L` is a location set and `Index` is some type that is inferred by the compiler. +/// If a location set `M` is a subset of `L`, then there exists a type `Index` such that `M` implements `Subset`. pub trait Subset {} // Base case: HNil is a subset of any set From feb84a27b9e7b9a39704026318c8c5de42fabd86 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sat, 30 Sep 2023 10:01:14 -0700 Subject: [PATCH 03/14] fix docs --- chorus_lib/src/core.rs | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/chorus_lib/src/core.rs b/chorus_lib/src/core.rs index 2c43e92..5fe334e 100644 --- a/chorus_lib/src/core.rs +++ b/chorus_lib/src/core.rs @@ -9,13 +9,25 @@ use serde::de::DeserializeOwned; #[doc(no_inline)] pub use serde::{Deserialize, Serialize}; -/// Represents a location. It can be derived using `#[derive(ChoreographyLocation)]`. +/// Represents a location. +/// +/// It can be derived using `#[derive(ChoreographyLocation)]`. +/// +/// ``` +/// # use chorus_lib::core::ChoreographyLocation; +/// # +/// #[derive(ChoreographyLocation)] +/// struct Alice; +/// ``` pub trait ChoreographyLocation: Copy { /// Returns the name of the location as a string. fn name() -> &'static str; } -/// Represents a value that can be used in a choreography. ChoRus uses [serde](https://serde.rs/) to serialize and deserialize values. +/// Represents a value that can be used in a choreography. +/// +/// ChoRus uses [serde](https://serde.rs/) to serialize and deserialize values. +/// /// It can be derived using `#[derive(Serialize, Deserialize)]` as long as all the fields satisfy the `Portable` trait. pub trait Portable: Serialize + DeserializeOwned {} impl Portable for T {} @@ -301,7 +313,7 @@ pub trait Choreography { /// /// The type parameter `L` is the location set that the transport is operating on. /// -/// The type paramter `TargetLocation` is the target `ChoreographyLocation`. +/// The type parameter `TargetLocation` is the target `ChoreographyLocation`. pub trait Transport { /// Returns a list of locations. fn locations(&self) -> Vec; From 8c02c2497496c5c07b67d8e0ef541cba0ec1446a Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sun, 1 Oct 2023 03:48:55 -0700 Subject: [PATCH 04/14] update comments in `hello.rs` --- chorus_lib/examples/hello.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/chorus_lib/examples/hello.rs b/chorus_lib/examples/hello.rs index f11f242..32176d9 100644 --- a/chorus_lib/examples/hello.rs +++ b/chorus_lib/examples/hello.rs @@ -18,6 +18,9 @@ struct HelloWorldChoreography; // Implement the `Choreography` trait for `HelloWorldChoreography` impl Choreography for HelloWorldChoreography { + // Define the set of locations involved in the choreography. + // In this case, the set consists of `Alice` and `Bob` and + // the choreography can use theses locations. type L = LocationSet!(Alice, Bob); fn run(self, op: &impl ChoreoOp) { // Create a located value at Alice From 34e44dd0545002c0b039ff3d2fa9b3ef4f054190 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sun, 1 Oct 2023 04:26:48 -0700 Subject: [PATCH 05/14] LocalTransportChannelBuilder --- chorus_book/src/guide-projector.md | 10 ++-- chorus_book/src/guide-transport.md | 28 +++++---- chorus_book/src/header.txt | 4 +- chorus_lib/examples/bookseller.rs | 8 ++- chorus_lib/examples/bookseller2.rs | 7 ++- chorus_lib/examples/hello.rs | 7 ++- chorus_lib/examples/loc-poly.rs | 7 ++- chorus_lib/src/transport/local.rs | 95 ++++++++++++++++++++++++------ 8 files changed, 121 insertions(+), 45 deletions(-) diff --git a/chorus_book/src/guide-projector.md b/chorus_book/src/guide-projector.md index 5378a8b..23bd0c2 100644 --- a/chorus_book/src/guide-projector.md +++ b/chorus_book/src/guide-projector.md @@ -8,14 +8,14 @@ To create a `Projector`, you need to provide the target location and the transpo ```rust # extern crate chorus_lib; -# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; # use chorus_lib::core::{ChoreographyLocation, Projector, LocationSet}; -# let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); -# let alice_transport = LocalTransport::new(Alice, transport_channel.clone()); # #[derive(ChoreographyLocation)] # struct Alice; # #[derive(ChoreographyLocation)] # struct Bob; +# let transport_channel = LocalTransportChannelBuilder::new().with(Alice).with(Bob).build(); +# let alice_transport = LocalTransport::new(Alice, transport_channel.clone()); let projector = Projector::new(Alice, alice_transport); ``` @@ -27,9 +27,9 @@ To execute a choreography, you need to call the `epp_and_run` method on the `Pro ```rust # extern crate chorus_lib; -# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; # use chorus_lib::core::{ChoreographyLocation, Projector, Choreography, ChoreoOp, LocationSet}; -# let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); +# let transport_channel = LocalTransportChannelBuilder::new().with(Alice).with(Bob).build(); # let alice_transport = LocalTransport::new(Alice, transport_channel.clone()); # #[derive(ChoreographyLocation)] # struct Alice; diff --git a/chorus_book/src/guide-transport.md b/chorus_book/src/guide-transport.md index 56f99db..085db99 100644 --- a/chorus_book/src/guide-transport.md +++ b/chorus_book/src/guide-transport.md @@ -8,7 +8,9 @@ ChoRus provides two built-in transports: `local` and `http`. ### The Local Transport -The `local` transport is used to execute choreographies on the same machine on different threads. This is useful for testing and prototyping. Each `local` transport is defined over `LocalTransportChannel`, which contains the set of `ChoreographyLocation` that the `local` transport operates on. You can build a `LocalTransportChannel` by importing the `LocalTransportChannel` struct from the `chorus_lib` crate. +The `local` transport is used to execute choreographies on the same machine on different threads. This is useful for testing and prototyping. + +To use the local transport, we first need to create a `LocalTransportChannel`, which works as a channel between threads and allows them to send messages to each other. To do so, we use the `LocalTransportChannelBuilder` struct from the `chorus_lib` crate. ```rust # extern crate chorus_lib; @@ -17,32 +19,35 @@ The `local` transport is used to execute choreographies on the same machine on d # struct Alice; # #[derive(ChoreographyLocation)] # struct Bob; -use chorus_lib::transport::local::LocalTransportChannel; +use chorus_lib::transport::local::LocalTransportChannelBuilder; -let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); +let transport_channel = LocalTransportChannelBuilder::new() + .with(Alice) + .with(Bob) + .build(); ``` -To use the `local` transport, first import the `LocalTransport` struct from the `chorus_lib` crate. +Using the `with` method, we add locations to the channel. When we call `build`, it will create an instance of `LocalTransportChannel`. -Then build the transport by using the `LocalTransport::new` associated function, which takes a target location (explained in the [Projector section](./guide-projector.md)) and the `LocalTransportChannel`. +Then, create a transport by using the `LocalTransport::new` function, which takes a target location (explained in the [Projector section](./guide-projector.md)) and the `LocalTransportChannel`. ```rust # extern crate chorus_lib; # use chorus_lib::core::{ChoreographyLocation, LocationSet}; # #[derive(ChoreographyLocation)] # struct Alice; -# use chorus_lib::transport::local::LocalTransportChannel; -# let transport_channel = LocalTransportChannel::new().with(Alice); +# use chorus_lib::transport::local::LocalTransportChannelBuilder; +# let transport_channel = LocalTransportChannelBuilder::new().with(Alice).build(); use chorus_lib::transport::local::{LocalTransport}; let alice_transport = LocalTransport::new(Alice, transport_channel.clone()); ``` -Because of the nature of the `Local` transport, you must use the same `LocalTransportChannel` instance for all locations. You can `clone` the `LocalTransprotChannel` instance and pass it to each `Projector::new` constructor. +Because of the nature of the `Local` transport, you must use the same `LocalTransportChannel` instance for all locations. You can `clone` the `LocalTransportChannel` instance and pass it to each `Projector::new` constructor. ```rust # extern crate chorus_lib; -# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; # use std::thread; # use chorus_lib::core::{ChoreographyLocation, ChoreoOp, Choreography, Projector, LocationSet}; # #[derive(ChoreographyLocation)] @@ -55,7 +60,10 @@ Because of the nature of the `Local` transport, you must use the same `LocalTran # fn run(self, op: &impl ChoreoOp) { # } # } -let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); +let transport_channel = LocalTransportChannelBuilder::new() + .with(Alice) + .with(Bob) + .build(); let mut handles: Vec> = Vec::new(); { // create a transport for Alice diff --git a/chorus_book/src/header.txt b/chorus_book/src/header.txt index d22111b..f24bfe6 100644 --- a/chorus_book/src/header.txt +++ b/chorus_book/src/header.txt @@ -1,13 +1,13 @@ # extern crate chorus_lib; # use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, Projector, Located, Superposition, Runner, LocationSet}; -# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; # #[derive(ChoreographyLocation)] # struct Alice; # #[derive(ChoreographyLocation)] # struct Bob; # #[derive(ChoreographyLocation)] # struct Carol; -# let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob).with(Carol); +# let transport_channel = LocalTransportChannelBuilder::new().with(Alice).with(Bob).with(Carol).build(); # let alice_transport = LocalTransport::new(Alice, transport_channel.clone()); # let bob_transport = LocalTransport::new(Bob, transport_channel.clone()); # let carol_transport = LocalTransport::new(Carol, transport_channel.clone()); \ No newline at end of file diff --git a/chorus_lib/examples/bookseller.rs b/chorus_lib/examples/bookseller.rs index 61152ea..2237be3 100644 --- a/chorus_lib/examples/bookseller.rs +++ b/chorus_lib/examples/bookseller.rs @@ -3,10 +3,11 @@ extern crate chorus_lib; use std::io; use std::thread; +use chorus_lib::transport::local::LocalTransportChannelBuilder; use chrono::NaiveDate; use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, LocationSet, Projector}; -use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +use chorus_lib::transport::local::LocalTransport; fn get_book(title: &str) -> Option<(i32, NaiveDate)> { match title.trim() { @@ -72,7 +73,10 @@ impl Choreography for BooksellerChoreography { } fn main() { - let transport_channel = LocalTransportChannel::new().with(Seller).with(Buyer); + let transport_channel = LocalTransportChannelBuilder::new() + .with(Seller) + .with(Buyer) + .build(); let transport_seller = LocalTransport::new(Seller, transport_channel.clone()); let transport_buyer = LocalTransport::new(Buyer, transport_channel.clone()); diff --git a/chorus_lib/examples/bookseller2.rs b/chorus_lib/examples/bookseller2.rs index e493af6..b62c0da 100644 --- a/chorus_lib/examples/bookseller2.rs +++ b/chorus_lib/examples/bookseller2.rs @@ -6,7 +6,7 @@ use std::thread; use chorus_lib::{ core::{ChoreoOp, Choreography, ChoreographyLocation, Located, LocationSet, Projector}, - transport::local::{LocalTransport, LocalTransportChannel}, + transport::local::{LocalTransport, LocalTransportChannelBuilder}, }; use chrono::NaiveDate; @@ -142,10 +142,11 @@ fn main() { i }; - let transport_channel = LocalTransportChannel::new() + let transport_channel = LocalTransportChannelBuilder::new() .with(Seller) .with(Buyer1) - .with(Buyer2); + .with(Buyer2) + .build(); let seller_projector = Arc::new(Projector::new( Seller, diff --git a/chorus_lib/examples/hello.rs b/chorus_lib/examples/hello.rs index 32176d9..ab10faa 100644 --- a/chorus_lib/examples/hello.rs +++ b/chorus_lib/examples/hello.rs @@ -3,7 +3,7 @@ extern crate chorus_lib; use std::thread; use chorus_lib::core::{ChoreoOp, Choreography, ChoreographyLocation, LocationSet, Projector}; -use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; // --- Define two locations (Alice and Bob) --- @@ -43,7 +43,10 @@ fn main() { let mut handles: Vec> = Vec::new(); // Create a transport channel // let transport_channel = LocalTransportChannel::::new(); - let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); + let transport_channel = LocalTransportChannelBuilder::new() + .with(Alice) + .with(Bob) + .build(); // Run the choreography in two threads { // let transport_channel = transport_channel.clone(); diff --git a/chorus_lib/examples/loc-poly.rs b/chorus_lib/examples/loc-poly.rs index f2a50d5..b12b3af 100644 --- a/chorus_lib/examples/loc-poly.rs +++ b/chorus_lib/examples/loc-poly.rs @@ -5,7 +5,7 @@ use std::thread; use chorus_lib::core::{ ChoreoOp, Choreography, ChoreographyLocation, Located, LocationSet, Portable, Projector, }; -use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; #[derive(ChoreographyLocation)] struct Alice; @@ -56,10 +56,11 @@ impl Choreography> for MainChoreography { } fn main() { - let transport_channel = LocalTransportChannel::new() + let transport_channel = LocalTransportChannelBuilder::new() .with(Alice) .with(Bob) - .with(Carol); + .with(Carol) + .build(); let mut handles = vec![]; { diff --git a/chorus_lib/src/transport/local.rs b/chorus_lib/src/transport/local.rs index 6533467..c8e8b31 100644 --- a/chorus_lib/src/transport/local.rs +++ b/chorus_lib/src/transport/local.rs @@ -28,25 +28,29 @@ impl Clone for LocalTransportChannel { } } -impl LocalTransportChannel { - /// Creates a new `LocalTransportChannel` instance - pub fn new() -> Self { - Self { - location_set: PhantomData, - queue_map: HashMap::new().into(), - } - } -} - impl LocalTransportChannel { - /// Adds a new location to the set of locations in the `LocalTransportChannel`. - pub fn with( - self, - _location: NewLocation, - ) -> LocalTransportChannel> { + /// Creates a new `LocalTransportChannel` instance. + /// + /// You must specify the location set of the channel. The channel can only be used by locations in the set. + /// + /// In most cases, you should use `LocalTransportChannelBuilder` instead of calling this method directly. + /// + /// # Examples + /// ``` + /// use chorus_lib::transport::local::{LocalTransportChannel}; + /// use chorus_lib::core::{LocationSet, ChoreographyLocation}; + /// + /// #[derive(ChoreographyLocation)] + /// struct Alice; + /// + /// #[derive(ChoreographyLocation)] + /// struct Bob; + /// + /// let transport_channel = LocalTransportChannel::::new(); + /// ``` + pub fn new() -> LocalTransportChannel { let mut queue_map: QueueMap = HashMap::new(); - let mut str_list = L::to_string_list(); - str_list.push(NewLocation::name()); + let str_list = L::to_string_list(); for sender in &str_list { let mut n = HashMap::new(); for receiver in &str_list { @@ -62,6 +66,58 @@ impl LocalTransportChannel { } } +/// A builder for `LocalTransportChannel`. +/// +/// Use this builder to create a `LocalTransportChannel` instance. +/// +/// # Examples +/// +/// ``` +/// use chorus_lib::core::{LocationSet, ChoreographyLocation}; +/// use chorus_lib::transport::local::{LocalTransportChannelBuilder}; +/// +/// #[derive(ChoreographyLocation)] +/// struct Alice; +/// +/// #[derive(ChoreographyLocation)] +/// struct Bob; +/// +/// let transport_channel = LocalTransportChannelBuilder::new() +/// .with(Alice) +/// .with(Bob) +/// .build(); +/// ``` +pub struct LocalTransportChannelBuilder { + location_set: PhantomData, +} + +impl LocalTransportChannelBuilder { + /// Creates a new `LocalTransportChannelBuilder` instance + pub fn new() -> Self { + Self { + location_set: PhantomData, + } + } +} + +impl LocalTransportChannelBuilder { + /// Adds a new location to the set of locations in the `LocalTransportChannel`. + pub fn with( + &self, + location: NewLocation, + ) -> LocalTransportChannelBuilder> { + _ = location; + LocalTransportChannelBuilder { + location_set: PhantomData, + } + } + + /// Builds a `LocalTransportChannel` instance. + pub fn build(&self) -> LocalTransportChannel { + LocalTransportChannel::new() + } +} + /// The local transport. /// /// This transport uses a blocking queue to allow for communication between threads. Each location must be executed in its thread. @@ -140,7 +196,10 @@ mod tests { fn test_local_transport() { let v = 42; - let transport_channel = LocalTransportChannel::new().with(Alice).with(Bob); + let transport_channel = LocalTransportChannelBuilder::new() + .with(Alice) + .with(Bob) + .build(); let mut handles = Vec::new(); { From e75b8f176cb5ea56a80683062e995169596d6a7c Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sun, 1 Oct 2023 05:02:41 -0700 Subject: [PATCH 06/14] refactor `TransportConfig` with a separate builder struct --- chorus_book/src/guide-transport.md | 23 +++++---- chorus_lib/examples/tic-tac-toe.rs | 13 ++--- chorus_lib/src/transport.rs | 76 ++++++++++++++++++++++-------- chorus_lib/src/transport/http.rs | 51 +++++++++++++++----- 4 files changed, 115 insertions(+), 48 deletions(-) diff --git a/chorus_book/src/guide-transport.md b/chorus_book/src/guide-transport.md index 085db99..82ed2ff 100644 --- a/chorus_book/src/guide-transport.md +++ b/chorus_book/src/guide-transport.md @@ -87,21 +87,23 @@ let mut handles: Vec> = Vec::new(); The `http` transport is used to execute choreographies on different machines. This is useful for executing choreographies in a distributed system. -To use the `http` transport, import the `HttpTransport` struct and the `HttpTransportConfig` type alias from the `chorus_lib` crate. +To use the `http` transport, import `HttpTransport` and `HttpTransportConfigBuilder` from the `chorus_lib` crate. ```rust # extern crate chorus_lib; -use chorus_lib::transport::http::{HttpTransport, HttpTransportConfig}; +use chorus_lib::transport::http::{HttpTransport, HttpTransportConfigBuilder}; ``` -The primary constructor requires an argument of type `HttpTransportConfig`. To create an instance of this configuration, start with `HttpTransportConfig::for_target(target_location, (hostname, port))`. It will create set a projection target and the hostname and port to listen on. Then, provide information to connect to other locations by method-chaining the `.with(other_location, (hostname, port))` method. You can think of `HttpTransportConfig` as a mapping from locations to their hostnames and ports. +We need to construct a `HttpTransportConfig` using the `HttpTransportConfigBuilder`. First, we specify the target location and the hostname and port to listen on using the `for_target` method. Then, we specify the other locations and their `(hostname, port)` pairs using the `with` method. ```rust {{#include ./header.txt}} -# use chorus_lib::transport::http::{HttpTransport, HttpTransportConfig}; -let config = HttpTransportConfig::for_target(Alice, ("localhost".to_string(), 8080)) - .with(Bob, ("localhost".to_string(), 8081)); - +# use chorus_lib::transport::http::{HttpTransport, HttpTransportConfigBuilder}; +// `Alice` listens on port 8080 on localhost +let config = HttpTransportConfigBuilder::for_target(Alice, ("localhost".to_string(), 8080)) + // Connect to `Bob` on port 8081 on localhost + .with(Bob, ("localhost".to_string(), 8081)) + .build(); let transport = HttpTransport::new(config); ``` @@ -113,10 +115,11 @@ You can also create your own transport by implementing the `Transport` trait. It ```rust {{#include ./header.txt}} -# use chorus_lib::transport::TransportConfig; -let config = TransportConfig::for_target(Alice, ()) +# use chorus_lib::transport::TransportConfigBuilder; +let config = TransportConfigBuilder::for_target(Alice, ()) .with(Bob, ("localhost".to_string(), 8081)) - .with(Carol, ("localhost".to_string(), 8082)); + .with(Carol, ("localhost".to_string(), 8082)) + .build(); ``` See the API documentation for more details. diff --git a/chorus_lib/examples/tic-tac-toe.rs b/chorus_lib/examples/tic-tac-toe.rs index 6a09302..3cc4518 100644 --- a/chorus_lib/examples/tic-tac-toe.rs +++ b/chorus_lib/examples/tic-tac-toe.rs @@ -1,13 +1,12 @@ /// Choreographic tik-tak-toe game extern crate chorus_lib; -use chorus_lib::transport::http::HttpTransportConfig; use chorus_lib::{ core::{ ChoreoOp, Choreography, ChoreographyLocation, Deserialize, Located, LocationSet, Projector, Serialize, }, - transport::http::HttpTransport, + transport::http::{HttpTransport, HttpTransportConfigBuilder}, }; use clap::Parser; @@ -295,7 +294,7 @@ fn main() { match args.player { 'X' => { - let config = HttpTransportConfig::for_target( + let config = HttpTransportConfigBuilder::for_target( PlayerX, (args.hostname.as_str().to_string(), args.port), ) @@ -305,7 +304,8 @@ fn main() { args.opponent_hostname.as_str().to_string(), args.opponent_port, ), - ); + ) + .build(); let transport = HttpTransport::new(config); let projector = Projector::new(PlayerX, transport); @@ -315,7 +315,7 @@ fn main() { }); } 'O' => { - let config = HttpTransportConfig::for_target( + let config = HttpTransportConfigBuilder::for_target( PlayerO, (args.hostname.as_str().to_string(), args.port), ) @@ -325,7 +325,8 @@ fn main() { args.opponent_hostname.as_str().to_string(), args.opponent_port, ), - ); + ) + .build(); let transport = HttpTransport::new(config); let projector = Projector::new(PlayerO, transport); diff --git a/chorus_lib/src/transport.rs b/chorus_lib/src/transport.rs index 6d98d8c..ee7c666 100644 --- a/chorus_lib/src/transport.rs +++ b/chorus_lib/src/transport.rs @@ -9,44 +9,80 @@ use std::marker::PhantomData; /// A generic struct for configuration of `Transport`. #[derive(Clone)] -pub struct TransportConfig -{ +pub struct TransportConfig { /// The information about locations - info: HashMap, + info: HashMap, /// The information about the target choreography - target_info: (TargetLocation, TargetInfoType), + target_info: (Target, TargetInfo), /// The struct is parametrized by the location set (`L`). location_set: PhantomData, } -impl - TransportConfig +/// A builder for `TransportConfig`. +/// +/// Use this builder to create a `TransportConfig` instance. +/// +/// # Examples +/// +/// ``` +/// use chorus_lib::core::{LocationSet, ChoreographyLocation}; +/// use chorus_lib::transport::TransportConfigBuilder; +/// +/// #[derive(ChoreographyLocation)] +/// struct Alice; +/// +/// #[derive(ChoreographyLocation)] +/// struct Bob; +/// +/// let transport_config = TransportConfigBuilder::for_target(Alice, "value_for_target".to_string()) +/// .with(Bob, "value_for_bob".to_string()) +/// .build(); +/// ``` +pub struct TransportConfigBuilder { + target: (Target, TargetInfo), + location_set: PhantomData, + info: HashMap<&'static str, Info>, +} + +impl + TransportConfigBuilder { - /// A transport for a given target. - pub fn for_target(location: TargetLocation, info: TargetInfoType) -> Self { + /// Creates a new `TransportConfigBuilder` instance for a given target. + pub fn for_target(target: Target, info: TargetInfo) -> Self { Self { - info: HashMap::new(), - target_info: (location, info), + target: (target, info), location_set: PhantomData, + info: HashMap::new(), } } } -impl - TransportConfig +impl + TransportConfigBuilder { /// Adds information about a new `ChoreographyLocation`. + /// + /// This method tells the builder that the choreography involves a new location and how to communicate with it. pub fn with( - mut self, - _location: NewLocation, - info: InfoType, - ) -> TransportConfig, InfoType, TargetLocation, TargetInfoType> -where { - self.info.insert(NewLocation::name().to_string(), info); + self, + location: NewLocation, + info: Info, + ) -> TransportConfigBuilder, Info> { + _ = location; + let mut new_info = self.info; + new_info.insert(NewLocation::name(), info); + TransportConfigBuilder { + target: self.target, + location_set: PhantomData, + info: new_info, + } + } + /// Builds a `TransportConfig` instance. + pub fn build(self) -> TransportConfig { TransportConfig { - info: self.info, - target_info: self.target_info, + info: HashMap::new(), + target_info: self.target, location_set: PhantomData, } } diff --git a/chorus_lib/src/transport/http.rs b/chorus_lib/src/transport/http.rs index 0c20a58..bb019ea 100644 --- a/chorus_lib/src/transport/http.rs +++ b/chorus_lib/src/transport/http.rs @@ -12,16 +12,37 @@ use retry::{ use tiny_http::Server; use ureq::{Agent, AgentBuilder}; -use crate::transport::TransportConfig; - use crate::{ core::{ChoreographyLocation, HList, Member, Portable, Transport}, + transport::{TransportConfig, TransportConfigBuilder}, utils::queue::BlockingQueue, }; type QueueMap = HashMap>; -/// A type alias for `TransportConfig`s used for building `HttpTransport` -pub type HttpTransportConfig = TransportConfig; + +/// Config for `HttpTransport`. +pub type HttpTransportConfig = TransportConfig; + +/// A builder for `HttpTransportConfig`. +/// +/// # Examples +/// +/// ``` +/// # use chorus_lib::core::{LocationSet, ChoreographyLocation}; +/// # use chorus_lib::transport::http::HttpTransportConfigBuilder; +/// # +/// # #[derive(ChoreographyLocation)] +/// # struct Alice; +/// # +/// # #[derive(ChoreographyLocation)] +/// # struct Bob; +/// # +/// let transport_config = HttpTransportConfigBuilder::for_target(Alice, ("0.0.0.0".to_string(), 9010)) +/// .with(Bob, ("example.com".to_string(), 80)) +/// .build(); +/// ``` +pub type HttpTransportConfigBuilder = + TransportConfigBuilder; /// The header name for the source location. const HEADER_SRC: &str = "X-CHORUS-SOURCE"; @@ -155,8 +176,10 @@ mod tests { let mut handles = Vec::new(); { - let config = HttpTransportConfig::for_target(Alice, ("0.0.0.0".to_string(), 9010)) - .with(Bob, ("localhost".to_string(), 9011)); + let config = + HttpTransportConfigBuilder::for_target(Alice, ("0.0.0.0".to_string(), 9010)) + .with(Bob, ("localhost".to_string(), 9011)) + .build(); handles.push(thread::spawn(move || { wait.recv().unwrap(); // wait for Bob to start @@ -165,8 +188,9 @@ mod tests { })); } { - let config = HttpTransportConfig::for_target(Bob, ("0.0.0.0".to_string(), 9011)) - .with(Alice, ("localhost".to_string(), 9010)); + let config = HttpTransportConfigBuilder::for_target(Bob, ("0.0.0.0".to_string(), 9011)) + .with(Alice, ("localhost".to_string(), 9010)) + .build(); handles.push(thread::spawn(move || { let transport = HttpTransport::new(config); @@ -187,8 +211,10 @@ mod tests { let mut handles = Vec::new(); { - let config = HttpTransportConfig::for_target(Alice, ("0.0.0.0".to_string(), 9020)) - .with(Bob, ("localhost".to_string(), 9021)); + let config = + HttpTransportConfigBuilder::for_target(Alice, ("0.0.0.0".to_string(), 9020)) + .with(Bob, ("localhost".to_string(), 9021)) + .build(); handles.push(thread::spawn(move || { signal.send(()).unwrap(); @@ -197,8 +223,9 @@ mod tests { })); } { - let config = HttpTransportConfig::for_target(Bob, ("0.0.0.0".to_string(), 9021)) - .with(Alice, ("localhost".to_string(), 9020)); + let config = HttpTransportConfigBuilder::for_target(Bob, ("0.0.0.0".to_string(), 9021)) + .with(Alice, ("localhost".to_string(), 9020)) + .build(); handles.push(thread::spawn(move || { // wait for Alice to start, which forces Alice to retry From cc6eed1b8c9cdd440bba2989784afa14cb918994 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sun, 1 Oct 2023 05:26:55 -0700 Subject: [PATCH 07/14] fix test --- chorus_lib/src/transport.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/chorus_lib/src/transport.rs b/chorus_lib/src/transport.rs index ee7c666..f040d9c 100644 --- a/chorus_lib/src/transport.rs +++ b/chorus_lib/src/transport.rs @@ -41,7 +41,7 @@ pub struct TransportConfig { target: (Target, TargetInfo), location_set: PhantomData, - info: HashMap<&'static str, Info>, + info: HashMap, } impl @@ -70,7 +70,7 @@ impl ) -> TransportConfigBuilder, Info> { _ = location; let mut new_info = self.info; - new_info.insert(NewLocation::name(), info); + new_info.insert(NewLocation::name().to_string(), info); TransportConfigBuilder { target: self.target, location_set: PhantomData, @@ -81,7 +81,7 @@ impl /// Builds a `TransportConfig` instance. pub fn build(self) -> TransportConfig { TransportConfig { - info: HashMap::new(), + info: self.info, target_info: self.target, location_set: PhantomData, } From 0c419a582da7716573ca96042f1397fc09369464 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Sun, 1 Oct 2023 05:39:33 -0700 Subject: [PATCH 08/14] public fields on `TransportConfig` --- chorus_lib/src/transport.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chorus_lib/src/transport.rs b/chorus_lib/src/transport.rs index f040d9c..1ddfc70 100644 --- a/chorus_lib/src/transport.rs +++ b/chorus_lib/src/transport.rs @@ -11,9 +11,9 @@ use std::marker::PhantomData; #[derive(Clone)] pub struct TransportConfig { /// The information about locations - info: HashMap, + pub info: HashMap, /// The information about the target choreography - target_info: (Target, TargetInfo), + pub target_info: (Target, TargetInfo), /// The struct is parametrized by the location set (`L`). location_set: PhantomData, } From 59bbab4790a5c2ff002b9dffb1926703c5c6414a Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Mon, 2 Oct 2023 12:14:42 -0700 Subject: [PATCH 09/14] fix failing example --- chorus_book/src/guide-transport.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chorus_book/src/guide-transport.md b/chorus_book/src/guide-transport.md index 82ed2ff..28ceee3 100644 --- a/chorus_book/src/guide-transport.md +++ b/chorus_book/src/guide-transport.md @@ -130,7 +130,7 @@ Note that when calling `epp_and_run` on a `Projector`, you will get a compile er ```rust, compile_fail # extern crate chorus_lib; -# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannel}; +# use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; # use chorus_lib::core::{ChoreographyLocation, Projector, Choreography, ChoreoOp}; # use chorus_lib::{LocationSet}; @@ -145,7 +145,7 @@ impl Choreography for HelloWorldChoreography { } } -let transport_channel = LocalTransportChannel::::new(); +let transport_channel = LocalTransportChannelBuilder::new().with(Alice).build(); let transport = LocalTransport::new(Alice, transport_channel.clone()); let projector = Projector::new(Alice, transport); projector.epp_and_run(HelloWorldChoreography); From de87e462e4fcd9a040c037e4e4fadb5d3e9d454c Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Mon, 2 Oct 2023 12:24:38 -0700 Subject: [PATCH 10/14] remove unnecessary comment --- chorus_lib/examples/hello.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/chorus_lib/examples/hello.rs b/chorus_lib/examples/hello.rs index ab10faa..34fe020 100644 --- a/chorus_lib/examples/hello.rs +++ b/chorus_lib/examples/hello.rs @@ -42,7 +42,6 @@ impl Choreography for HelloWorldChoreography { fn main() { let mut handles: Vec> = Vec::new(); // Create a transport channel - // let transport_channel = LocalTransportChannel::::new(); let transport_channel = LocalTransportChannelBuilder::new() .with(Alice) .with(Bob) From 1a0f0e1da56163f169f03775398da0dba254b2a7 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Mon, 2 Oct 2023 12:25:19 -0700 Subject: [PATCH 11/14] remove more unnecessary comments --- chorus_lib/examples/hello.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/chorus_lib/examples/hello.rs b/chorus_lib/examples/hello.rs index 34fe020..f861ed2 100644 --- a/chorus_lib/examples/hello.rs +++ b/chorus_lib/examples/hello.rs @@ -48,7 +48,6 @@ fn main() { .build(); // Run the choreography in two threads { - // let transport_channel = transport_channel.clone(); let transport = LocalTransport::new(Alice, transport_channel.clone()); handles.push(thread::spawn(move || { let p = Projector::new(Alice, transport); @@ -56,7 +55,6 @@ fn main() { })); } { - // let transport_channel = transport_channel.clone(); let transport = LocalTransport::new(Bob, transport_channel.clone()); handles.push(thread::spawn(move || { let p = Projector::new(Bob, transport); From 5c907758ee60daf7f1e69278eaeb869a08c94ff8 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Mon, 2 Oct 2023 12:27:02 -0700 Subject: [PATCH 12/14] adjust comment --- chorus_lib/src/transport/local.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chorus_lib/src/transport/local.rs b/chorus_lib/src/transport/local.rs index c8e8b31..7026717 100644 --- a/chorus_lib/src/transport/local.rs +++ b/chorus_lib/src/transport/local.rs @@ -122,7 +122,7 @@ impl LocalTransportChannelBuilder { /// /// This transport uses a blocking queue to allow for communication between threads. Each location must be executed in its thread. /// -/// Unlike network-based transports, all locations must share the same `LocalTransport` instance. The struct implements `Clone` so that it can be shared across threads. +/// All locations must share the same `LocalTransportChannel` instance. `LocalTransportChannel` implements `Clone` so that it can be shared across threads. pub struct LocalTransport { internal_locations: Vec, location_set: PhantomData, From d4f96a4ab1c168e904790462a5679c67da22385d Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Mon, 2 Oct 2023 12:29:13 -0700 Subject: [PATCH 13/14] remove underscore for better hints --- chorus_lib/src/core.rs | 3 ++- chorus_lib/src/transport/local.rs | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/chorus_lib/src/core.rs b/chorus_lib/src/core.rs index 5fe334e..426ad39 100644 --- a/chorus_lib/src/core.rs +++ b/chorus_lib/src/core.rs @@ -342,7 +342,8 @@ where /// /// - `target` is the projection target of the choreography. /// - `transport` is an implementation of `Transport`. - pub fn new(_target: L1, transport: B) -> Self { + pub fn new(target: L1, transport: B) -> Self { + _ = target; Projector { target: PhantomData, transport, diff --git a/chorus_lib/src/transport/local.rs b/chorus_lib/src/transport/local.rs index 7026717..9e7f447 100644 --- a/chorus_lib/src/transport/local.rs +++ b/chorus_lib/src/transport/local.rs @@ -132,7 +132,9 @@ pub struct LocalTransport { impl LocalTransport { /// Creates a new `LocalTransport` instance from a Target `ChoreographyLocation` and a `LocalTransportChannel`. - pub fn new(_target: TargetLocation, local_channel: LocalTransportChannel) -> Self { + pub fn new(target: TargetLocation, local_channel: LocalTransportChannel) -> Self { + _ = target; + let locations_list = L::to_string_list(); let mut locations_vec = Vec::new(); From 4663697e98a1887c28e685dc82378f5a565c5b31 Mon Sep 17 00:00:00 2001 From: Shun Kashiwa Date: Mon, 2 Oct 2023 12:40:00 -0700 Subject: [PATCH 14/14] fix import path --- chorus_book/src/guide-transport.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/chorus_book/src/guide-transport.md b/chorus_book/src/guide-transport.md index 28ceee3..aceab44 100644 --- a/chorus_book/src/guide-transport.md +++ b/chorus_book/src/guide-transport.md @@ -131,8 +131,7 @@ Note that when calling `epp_and_run` on a `Projector`, you will get a compile er ```rust, compile_fail # extern crate chorus_lib; # use chorus_lib::transport::local::{LocalTransport, LocalTransportChannelBuilder}; -# use chorus_lib::core::{ChoreographyLocation, Projector, Choreography, ChoreoOp}; -# use chorus_lib::{LocationSet}; +# use chorus_lib::core::{ChoreographyLocation, Projector, Choreography, ChoreoOp, LocationSet}; # #[derive(ChoreographyLocation)] # struct Alice;