From 8ff02690cebc97f70f17d86e0a10a230929c0928 Mon Sep 17 00:00:00 2001 From: Soroush Zare Date: Thu, 5 Oct 2023 12:52:40 -0700 Subject: [PATCH 1/5] Add a section for LocationSet in the book --- chorus_book/src/guide-choreography.md | 2 +- chorus_book/src/guide-locations.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/chorus_book/src/guide-choreography.md b/chorus_book/src/guide-choreography.md index 32003c3..1480948 100644 --- a/chorus_book/src/guide-choreography.md +++ b/chorus_book/src/guide-choreography.md @@ -21,7 +21,7 @@ impl Choreography for HelloWorldChoreography { `Choreography` must implement the `run` method which defines the behavior of the system. The `run` method takes a reference to an object that implements the `ChoreoOp` trait. The `ChoreoOp` trait provides choreographic operators such as `locally` and `comm`. -Also, each `Choreography` has an associated type `L`, called it's location set; this is the set of `ChoreographyLocation`s that the `Choreography` can operate on. To build a location set, you can use the macro `LocationSet!`. +Also, each `Choreography` has an associated `LocationSet` type, `L`; this is the `LocationSet` that the `Choreography` can operate on. ## Choreographic Operators diff --git a/chorus_book/src/guide-locations.md b/chorus_book/src/guide-locations.md index 3e5c2b8..76aec76 100644 --- a/chorus_book/src/guide-locations.md +++ b/chorus_book/src/guide-locations.md @@ -29,3 +29,22 @@ The `ChoreographyLocation` trait provides the `name` method, which returns the n let name = Alice::name(); assert_eq!(name, "Alice"); ``` + +## Location Set + +Each Choreography is allowed to operate on a set of `ChoreographyLocation`, called its `LocationSet`. You can use the macro `LocationSet!` and give it a comma separated list of `ChoreographyLocation` to build a `LocationSet`. + +```rust +# extern crate chorus_lib; +# use chorus_lib::core::ChoreographyLocation; +# #[derive(ChoreographyLocation)] +# struct Alice; +# +# #[derive(ChoreographyLocation)] +# struct Bob; +use chorus_lib::core::LocationSet; + +type L = LocationSet!(Alice, Bob); +``` + +Internally, `LocationSet` is also used at other places like [Projector](./guide-projector.md) and [Transport](./guide-transport.md) to ensure that they have comprehensive information regarding the `ChoreographyLocation` values they're working with. This is crucial as it allows the system to catch potential errors during compile time instead of runtime, leading to safer code. You can check the API documentation for more details. From 8868303d6cb8fe3ab5cd2fac5b35b038f2470806 Mon Sep 17 00:00:00 2001 From: Soroush Zare Date: Thu, 5 Oct 2023 13:02:42 -0700 Subject: [PATCH 2/5] Change the documentation for custom transports --- chorus_book/src/guide-transport.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chorus_book/src/guide-transport.md b/chorus_book/src/guide-transport.md index aceab44..40879dd 100644 --- a/chorus_book/src/guide-transport.md +++ b/chorus_book/src/guide-transport.md @@ -111,7 +111,7 @@ In the above example, the transport will start the HTTP server on port 8080 on l ## Creating a Custom Transport -You can also create your own transport by implementing the `Transport` trait. It might be helpful first build a `TransportConfig` to have the the information that you need for each `ChoreographyLocation`, and then have a constructor that takes the `TransportConfig` and builds the `Transport` based on it. While the syntax is similar to `HttpTransportConfig`, the type of information for each `ChoreographyLocation` might diverge from the `(host_name, port)` format presented here. In some cases, the `target_information` could even have a different type than the following `other_location_information` types. But all the `other_location_information`s should have the same type. +You can also create your own transport by implementing the `Transport` trait. It might be helpful to first build a `TransportConfig` to have the the information that you need for each `ChoreographyLocation`, and then have a constructor that takes the `TransportConfig` and builds the `Transport` based on it. While the syntax is similar to `HttpTransportConfig`, which is `HttpTransportConfigBuilder::for_target(target_location, target_information)`, chained with information about other locations using the `.with(other_location, other_location_information)`, the type of information for each `ChoreographyLocation` might diverge from the `(host_name, port)` format presented in `HttpTransport`. In some cases, the `target_information` could even have a different type than the following `other_location_information` types. But all the `other_location_information`s should have the same type. ```rust {{#include ./header.txt}} From fc1b4cd9fe537305869cfc46e76f036cdb5dd828 Mon Sep 17 00:00:00 2001 From: Soroush Zare Date: Fri, 6 Oct 2023 06:22:33 -0700 Subject: [PATCH 3/5] Remove unnecessary informations about LocationSet --- chorus_book/src/guide-locations.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/chorus_book/src/guide-locations.md b/chorus_book/src/guide-locations.md index 76aec76..0df45cc 100644 --- a/chorus_book/src/guide-locations.md +++ b/chorus_book/src/guide-locations.md @@ -32,7 +32,8 @@ assert_eq!(name, "Alice"); ## Location Set -Each Choreography is allowed to operate on a set of `ChoreographyLocation`, called its `LocationSet`. You can use the macro `LocationSet!` and give it a comma separated list of `ChoreographyLocation` to build a `LocationSet`. +A `LocationSet` is a set of `ChoreographyLocation` values. It's primarily used to ensure type safety within the system, and you'll see its application in future sections. + ```rust # extern crate chorus_lib; @@ -46,5 +47,3 @@ use chorus_lib::core::LocationSet; type L = LocationSet!(Alice, Bob); ``` - -Internally, `LocationSet` is also used at other places like [Projector](./guide-projector.md) and [Transport](./guide-transport.md) to ensure that they have comprehensive information regarding the `ChoreographyLocation` values they're working with. This is crucial as it allows the system to catch potential errors during compile time instead of runtime, leading to safer code. You can check the API documentation for more details. From 23b6079910a7b3b4533ac8c27be3a281b159cfe7 Mon Sep 17 00:00:00 2001 From: Soroush Zare Date: Fri, 6 Oct 2023 14:23:15 -0700 Subject: [PATCH 4/5] Update chorus_book/src/guide-locations.md Co-authored-by: Shun Kashiwa --- chorus_book/src/guide-locations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chorus_book/src/guide-locations.md b/chorus_book/src/guide-locations.md index 0df45cc..ff838da 100644 --- a/chorus_book/src/guide-locations.md +++ b/chorus_book/src/guide-locations.md @@ -32,7 +32,7 @@ assert_eq!(name, "Alice"); ## Location Set -A `LocationSet` is a set of `ChoreographyLocation` values. It's primarily used to ensure type safety within the system, and you'll see its application in future sections. +A `LocationSet` is a special type representing a set of `ChoreographyLocation` types. It's used to ensure type safety within the system, and you'll see its application in future sections. ```rust From 2ba79a39d9f4756e7499ab3c8603706ebbb2c1ed Mon Sep 17 00:00:00 2001 From: Soroush Zare Date: Fri, 6 Oct 2023 14:30:34 -0700 Subject: [PATCH 5/5] Add a note on how to build a LocationSet using the LocationSet macro --- chorus_book/src/guide-locations.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/chorus_book/src/guide-locations.md b/chorus_book/src/guide-locations.md index ff838da..f26ffe9 100644 --- a/chorus_book/src/guide-locations.md +++ b/chorus_book/src/guide-locations.md @@ -32,8 +32,7 @@ assert_eq!(name, "Alice"); ## Location Set -A `LocationSet` is a special type representing a set of `ChoreographyLocation` types. It's used to ensure type safety within the system, and you'll see its application in future sections. - +A `LocationSet` is a special type representing a set of `ChoreographyLocation` types. It's used to ensure type safety within the system, and you'll see its application in future sections. To build a `LocationSet` type, you can use the `LocationSet` macro from the `chorus_lib` crate. ```rust # extern crate chorus_lib;