From e8fd42aeb72249cb78e75fc654d885715cda4b9e Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 11:47:13 -0500 Subject: [PATCH 1/9] minor fixups --- documentation/01-Prerequisites.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/documentation/01-Prerequisites.md b/documentation/01-Prerequisites.md index f4abd295721..e23f45721a6 100644 --- a/documentation/01-Prerequisites.md +++ b/documentation/01-Prerequisites.md @@ -6,7 +6,7 @@ These are one-time setup instructions that should be executed prior to following - [Prerequisites for building and using MLOS](#prerequisites-for-building-and-using-mlos) - [Contents](#contents) - - [Cloning the repository](#clone-the-repository) + - [Clone the repository](#clone-the-repository) - [Python quickstart](#python-quickstart) - [Linux](#linux) - [Linux Distribution Requirements](#linux-distribution-requirements) @@ -21,11 +21,11 @@ These are one-time setup instructions that should be executed prior to following - [Step 1: Install Python](#step-1-install-python) - [Step 2: Install Docker on Windows](#step-2-install-docker-on-windows) - [Step 3: Install Windows Build Tools](#step-3-install-windows-build-tools) + - [Step 4: Build the Docker image](#step-4-build-the-docker-image) MLOS currently supports 64-bit Intel/AMD platforms, though ARM64 support is under development. It supports Windows and Linux environments. Below we provide instructions for each OS. - ## Clone the repository Make sure you have [git](https://git-scm.com/) installed and clone the repo: @@ -79,7 +79,6 @@ All of them require `git` and, of course, a Linux installation: > Other distros/versions may work, but are untested. - ### Option 1: Linux Docker Build Env #### Install Docker @@ -154,8 +153,6 @@ Follow the [Python Quickstart](#python-quickstart) above. MLOS is easiest to use on Windows 10, Version 1903 (March 2019) or newer. - - ### Step 1: Install Python Follow the [Python Quickstart](#python-quickstart) above. @@ -173,3 +170,7 @@ Download and install Visual Studio 2019 (free) Community Edition: Be sure to include support for .Net Core and C++. + +### Step 4: Build the Docker image + +The instructions for [building the docker image](#build-the-docker-image) are the same as for Linux. From ff0701dbdf2b2769663c6e9ba98f3d882ab8d591 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 11:47:27 -0500 Subject: [PATCH 2/9] start some instructions and explanations on running the SmartCache end to end example --- source/Examples/SmartCache/README.md | 115 +++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 source/Examples/SmartCache/README.md diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md new file mode 100644 index 00000000000..7b59c35ba60 --- /dev/null +++ b/source/Examples/SmartCache/README.md @@ -0,0 +1,115 @@ +# SmartCache Example + +TODO: Some description of the example contained in this directory. + +This `SmartCache` can be used to demonstrate a full end-to-end MLOS integrated microbenchmark for a "smart" component (in this case a cache). + +## Overview + +To do that, we run the (C++) `SmartCache` executable to communicate with the (C#) [`Mlos.Agent.Server`](../../Mlos.Agent.Server/) over a shared memory channel provided by the [`Mlos.Core`](../../Mlos.Core/) library. + +The `Mlos.Agent.Server` is essentially a small wrapper around several other communication channels to allow different components to connect for component experimentation convenience. + +It provides + +1. Shared memory communication channels via the [`Mlos.Agent`](../../Mlos.Agent) and [`Mlos.NetCore`](../../Mlos.NetCore) libraries. + +2. A [`Mlos.Agent.GrpcServer`](../../Mlos.Agent.GrpcClient/) GRPC channel to allow driving the experimentation process from a Jupyter notebook. + +3. A GRPC client to connect to the (Python) [`mlos.Grpc.OptimizerMicroserviceServer`](../../Mlos.Python/mlos/Grpc/OptimizerMicroserviceServer.py) to store and track those experiments. + +TODO: Diagrams + +## Building + +To build and run the necessary components for this example + +1. [Build the Docker image](../../../documentation/01-Prerequisites.md#build-the-docker-image) using the [`Dockerfile`](../../../Dockerfile) at the root of the repository. + +2. [Run the Docker image](../../../documentation/02-Build.md#create-a-new-container-instance) you just built. + +3. Inside the container, [build the compiled software](../../../documentation/02-Build.md#cli-make) with `make`: + + ```sh + make dotnet-build cmake-build + ``` + + > This will build everything using a default `CONFIGURATION=Release`. + > + > To just build `SmartCache` and `Mlos.Agent.Server`, execute the following: \ + > `make -C source/Examples/SmartCache && make -C source/Mlos.Agent.Server` + +4. For a `Release` build, the relevant output will be at: + + - `Mlos.Agent.Server`: + + `out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll` + + - `SmartCache`: + + `out/cmake/Release/source/Examples/SmartCache/SmartCache` + + - `SmartCache.SettingsRegistry` + + `out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU/SmartCache.SettingsRegistry.dll` + +## Executing + +> Note: these commands are given relative to the root of the MLOS repo. +> +> To move there, you can execute the following within the repository: +> +> `cd $(git rev-parse --show-toplevel)` + +`SmartCache` can be invoked separate, or by the `Mlos.Agent.Server` itself. + +Once started, `SmartCache` will attempt to register its component specific set of shared memory messages with the `Mlos.Agent` in the `Mlos.Agent.Server` using some `Mlos.Core` component registration messages. That message includes the name of the `SettingsRegistry` assembly (`.dll`) corresponding to that component's settings/messages. + +The `Mlos.Agent.Server` needs to be told where it can find those assemblies. To do that we provide an `MLOS_SETTINGS_REGISTRY_PATH` environment variable. + +In this case we populate it with the path to the `SmartCache.SettingsRegistry.dll`: + +```sh +export MLOS_SETTINGS_REGISTRY_PATH="out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU:$MLOS_SETTINGS_REGISTRY_PATH" +``` + +Next, we can the `Mlos.Server.Agent` using the `dotnet` command: + +```sh +tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll +# FIXME: This is missing the .json file to connect to the optimizer service. +``` + +The `Mlos.Agent` that gets started will then wait for a signal that the other side (`SmartCache`) has connected to the shared memory region before started to poll it for messages to process. + +To start the `SmartCache` process we first need another shell instance in the docker container: + +```sh +docker exec -it mlos-build /bin/bash +``` + +Now, we can start `SmartCache` as follows: + +```sh +out/cmake/Release/source/Examples/SmartCache/SmartCache +``` + +> To have `Mlos.Agent.Server` start `SmartCache` without having to start another shell in the docker container instance, add the path to the `SmartCache` binary as an argument to the `dotnet ... Mlos.Agent.Server` invocation. + +## Caveats + +- The system currently only supports one shared memory region and doesn't cleanup the shared memory after itself. + + To help with this, we currently provide a helper script to remove previous incarnations of the shared memory regions: + + ```sh + build/CMakeHelpers/RemoveMlosSharedMemories.sh + ``` + + You may also need to make sure that the processes using them are killed off. + For instance: + + ```sh + pkill SmartCache + pkill -f dotnet.*Mlos.Agent.Server.dll + ``` From 586620af02aa93d360d5cdd7d869d9bd7dc51a01 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 11:55:38 -0500 Subject: [PATCH 3/9] add the docker build/run commands in explicitly --- source/Examples/SmartCache/README.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md index 7b59c35ba60..e459d929b35 100644 --- a/source/Examples/SmartCache/README.md +++ b/source/Examples/SmartCache/README.md @@ -22,12 +22,26 @@ TODO: Diagrams ## Building +> Note: these commands are given relative to the root of the MLOS repo. +> +> To move there, you can execute the following within the repository: +> +> `cd $(git rev-parse --show-toplevel)` + To build and run the necessary components for this example 1. [Build the Docker image](../../../documentation/01-Prerequisites.md#build-the-docker-image) using the [`Dockerfile`](../../../Dockerfile) at the root of the repository. + ```shell + docker build --build-arg=UbuntuVersion=20.04 -t mlos/build:ubuntu-20.04 . + ``` + 2. [Run the Docker image](../../../documentation/02-Build.md#create-a-new-container-instance) you just built. + ```shell + docker run -it -v $PWD:/src/MLOS --name mlos-build mlos/build:ubuntu-20.0 + ``` + 3. Inside the container, [build the compiled software](../../../documentation/02-Build.md#cli-make) with `make`: ```sh @@ -55,12 +69,6 @@ To build and run the necessary components for this example ## Executing -> Note: these commands are given relative to the root of the MLOS repo. -> -> To move there, you can execute the following within the repository: -> -> `cd $(git rev-parse --show-toplevel)` - `SmartCache` can be invoked separate, or by the `Mlos.Agent.Server` itself. Once started, `SmartCache` will attempt to register its component specific set of shared memory messages with the `Mlos.Agent` in the `Mlos.Agent.Server` using some `Mlos.Core` component registration messages. That message includes the name of the `SettingsRegistry` assembly (`.dll`) corresponding to that component's settings/messages. From c401cadfcf6a0a1097257be958cc6ee5dc6a6773 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 14:41:36 -0500 Subject: [PATCH 4/9] Update source/Examples/SmartCache/README.md Co-authored-by: Andreas Mueller --- source/Examples/SmartCache/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md index e459d929b35..d3c252d273c 100644 --- a/source/Examples/SmartCache/README.md +++ b/source/Examples/SmartCache/README.md @@ -53,7 +53,7 @@ To build and run the necessary components for this example > To just build `SmartCache` and `Mlos.Agent.Server`, execute the following: \ > `make -C source/Examples/SmartCache && make -C source/Mlos.Agent.Server` -4. For a `Release` build, the relevant output will be at: +4. For a `Release` build (the default), the relevant output will be at: - `Mlos.Agent.Server`: From c113b3411a0ac556c4228b773cf641c89841a5ef Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 14:42:58 -0500 Subject: [PATCH 5/9] Update source/Examples/SmartCache/README.md Co-authored-by: Andreas Mueller --- source/Examples/SmartCache/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md index d3c252d273c..508b30b946e 100644 --- a/source/Examples/SmartCache/README.md +++ b/source/Examples/SmartCache/README.md @@ -81,7 +81,7 @@ In this case we populate it with the path to the `SmartCache.SettingsRegistry.dl export MLOS_SETTINGS_REGISTRY_PATH="out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU:$MLOS_SETTINGS_REGISTRY_PATH" ``` -Next, we can the `Mlos.Server.Agent` using the `dotnet` command: +Next, we can start the `Mlos.Server.Agent` using the `dotnet` command: ```sh tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll From c5fa3401e86b767e05959691749775fe22291e0b Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 14:43:23 -0500 Subject: [PATCH 6/9] Update source/Examples/SmartCache/README.md Co-authored-by: Andreas Mueller --- source/Examples/SmartCache/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md index 508b30b946e..f6b76406f9c 100644 --- a/source/Examples/SmartCache/README.md +++ b/source/Examples/SmartCache/README.md @@ -88,7 +88,7 @@ tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Serve # FIXME: This is missing the .json file to connect to the optimizer service. ``` -The `Mlos.Agent` that gets started will then wait for a signal that the other side (`SmartCache`) has connected to the shared memory region before started to poll it for messages to process. +The `Mlos.Agent` that gets started will then wait for a signal that the component (`SmartCache`) has connected to the shared memory region before starting to poll the component for messages to process. To start the `SmartCache` process we first need another shell instance in the docker container: From 6cdf2fcfe5ef7b655ee636a13484f2df29290b0f Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 14:56:58 -0500 Subject: [PATCH 7/9] link tweaks --- source/Examples/SmartCache/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md index f6b76406f9c..fddfc69b871 100644 --- a/source/Examples/SmartCache/README.md +++ b/source/Examples/SmartCache/README.md @@ -6,17 +6,17 @@ This `SmartCache` can be used to demonstrate a full end-to-end MLOS integrated m ## Overview -To do that, we run the (C++) `SmartCache` executable to communicate with the (C#) [`Mlos.Agent.Server`](../../Mlos.Agent.Server/) over a shared memory channel provided by the [`Mlos.Core`](../../Mlos.Core/) library. +To do that, we run the (C++) `SmartCache` executable to communicate with the (C#) [`Mlos.Agent.Server`](../../Mlos.Agent.Server/#mlos-github-tree-view) over a shared memory channel provided by the [`Mlos.Core`](../../Mlos.Core/#mlos-github-tree-view) library. The `Mlos.Agent.Server` is essentially a small wrapper around several other communication channels to allow different components to connect for component experimentation convenience. It provides -1. Shared memory communication channels via the [`Mlos.Agent`](../../Mlos.Agent) and [`Mlos.NetCore`](../../Mlos.NetCore) libraries. +1. Shared memory communication channels via the [`Mlos.Agent`](../../Mlos.Agent/#mlos-github-tree-view) and [`Mlos.NetCore`](../../Mlos.NetCore/#mlos-github-tree-view) libraries. -2. A [`Mlos.Agent.GrpcServer`](../../Mlos.Agent.GrpcClient/) GRPC channel to allow driving the experimentation process from a Jupyter notebook. +2. A [`Mlos.Agent.GrpcServer`](../../Mlos.Agent.GrpcClient/#mlos-github-tree-view) GRPC channel to allow driving the experimentation process from a Jupyter notebook. -3. A GRPC client to connect to the (Python) [`mlos.Grpc.OptimizerMicroserviceServer`](../../Mlos.Python/mlos/Grpc/OptimizerMicroserviceServer.py) to store and track those experiments. +3. A GRPC client to connect to the (Python) [`mlos.Grpc.OptimizerMicroserviceServer`](../../Mlos.Python/mlos/Grpc/OptimizerMicroserviceServer.py#mlos-github-tree-view) to store and track those experiments. TODO: Diagrams @@ -30,7 +30,7 @@ TODO: Diagrams To build and run the necessary components for this example -1. [Build the Docker image](../../../documentation/01-Prerequisites.md#build-the-docker-image) using the [`Dockerfile`](../../../Dockerfile) at the root of the repository. +1. [Build the Docker image](../../../documentation/01-Prerequisites.md#build-the-docker-image) using the [`Dockerfile`](../../../Dockerfile#mlos-github-tree-view) at the root of the repository. ```shell docker build --build-arg=UbuntuVersion=20.04 -t mlos/build:ubuntu-20.04 . @@ -55,15 +55,15 @@ To build and run the necessary components for this example 4. For a `Release` build (the default), the relevant output will be at: - - `Mlos.Agent.Server`: + - Mlos.Agent.Server: `out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll` - - `SmartCache`: + - SmartCache: `out/cmake/Release/source/Examples/SmartCache/SmartCache` - - `SmartCache.SettingsRegistry` + - SmartCache.SettingsRegistry: `out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU/SmartCache.SettingsRegistry.dll` @@ -85,7 +85,7 @@ Next, we can start the `Mlos.Server.Agent` using the `dotnet` command: ```sh tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll -# FIXME: This is missing the .json file to connect to the optimizer service. +# Note: This is missing the .json file to connect to the optimizer service. ``` The `Mlos.Agent` that gets started will then wait for a signal that the component (`SmartCache`) has connected to the shared memory region before starting to poll the component for messages to process. From ebdfd10733e07cb2b498831462b8381a84d90aee Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 15:19:53 -0500 Subject: [PATCH 8/9] reorg to address some comments --- source/Examples/SmartCache/README.md | 63 +++++++++++++++++----------- 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md index fddfc69b871..b44dc62de70 100644 --- a/source/Examples/SmartCache/README.md +++ b/source/Examples/SmartCache/README.md @@ -69,45 +69,58 @@ To build and run the necessary components for this example ## Executing -`SmartCache` can be invoked separate, or by the `Mlos.Agent.Server` itself. - -Once started, `SmartCache` will attempt to register its component specific set of shared memory messages with the `Mlos.Agent` in the `Mlos.Agent.Server` using some `Mlos.Core` component registration messages. That message includes the name of the `SettingsRegistry` assembly (`.dll`) corresponding to that component's settings/messages. - -The `Mlos.Agent.Server` needs to be told where it can find those assemblies. To do that we provide an `MLOS_SETTINGS_REGISTRY_PATH` environment variable. - -In this case we populate it with the path to the `SmartCache.SettingsRegistry.dll`: +The following commands will start the `Mlos.Server.Agent` and cause it to start the `SmartCache` component microbenchmark: ```sh -export MLOS_SETTINGS_REGISTRY_PATH="out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU:$MLOS_SETTINGS_REGISTRY_PATH" -``` +export MLOS_SETTINGS_REGISTRY_PATH="out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU" -Next, we can start the `Mlos.Server.Agent` using the `dotnet` command: +tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll \ + out/cmake/Release/source/Examples/SmartCache/SmartCache +``` -```sh -tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll -# Note: This is missing the .json file to connect to the optimizer service. +> Note: This is currently missing the `.json` file argument to connect to the optimizer service. + +```txt +Mlos.Agent.Server +Starting out/cmake/Release/source/Examples/SmartCache/SmartCache +observations: 0 +warn: Microsoft.AspNetCore.Server.Kestrel[0] + Unable to bind to http://localhost:5000 on the IPv6 loopback interface: 'Cannot assign requested address'. +info: Microsoft.Hosting.Lifetime[0] + Now listening on: http://localhost:5000 +info: Microsoft.Hosting.Lifetime[0] + Application started. Press Ctrl+C to shut down. +info: Microsoft.Hosting.Lifetime[0] + Hosting environment: Production +info: Microsoft.Hosting.Lifetime[0] + Content root path: /src/MLOS +Starting Mlos.Agent +Found settings registry assembly at out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU/SmartCache.SettingsRegistry.dll +observations: 1 +observations: 2 +observations: 3 +... ``` -The `Mlos.Agent` that gets started will then wait for a signal that the component (`SmartCache`) has connected to the shared memory region before starting to poll the component for messages to process. +### Explanation -To start the `SmartCache` process we first need another shell instance in the docker container: +The `Mlos.Agent` that gets started by the `Mlos.Agent.Server` waits for a signal that the component (`SmartCache`) has connected to the shared memory region before starting to poll the component for messages to process. +This is important in case the component is started independently. -```sh -docker exec -it mlos-build /bin/bash -``` - -Now, we can start `SmartCache` as follows: +In this case, `Mlos.Agent.Server` itself starts the component. -```sh -out/cmake/Release/source/Examples/SmartCache/SmartCache -``` +Once started, `SmartCache` will attempt to register its component specific set of shared memory messages with the `Mlos.Agent` in the `Mlos.Agent.Server` using `RegisterComponentConfig` and `RegisterAssemblyRequestMessage` from `Mlos.Core` and `Mlos.NetCore`. +That includes the name of the `SettingsRegistry` assembly (`.dll`) corresponding to that component's settings/messages. -> To have `Mlos.Agent.Server` start `SmartCache` without having to start another shell in the docker container instance, add the path to the `SmartCache` binary as an argument to the `dotnet ... Mlos.Agent.Server` invocation. +The `Mlos.Agent.Server` needs to be told where it can find those assemblies in order to load them so that it can process the messages sent by the component. +To do that, before we started the `Mlos.Agent.Server`, we first populated the `MLOS_SETTINGS_REGISTRY_PATH` environment variable with the directory path to the `SmartCache.SettingsRegistry.dll`. ## Caveats - The system currently only supports one shared memory region and doesn't cleanup the shared memory after itself. + As such, you may see hung processes when restarting after a failed experiment. + To help with this, we currently provide a helper script to remove previous incarnations of the shared memory regions: ```sh @@ -121,3 +134,5 @@ out/cmake/Release/source/Examples/SmartCache/SmartCache pkill SmartCache pkill -f dotnet.*Mlos.Agent.Server.dll ``` + + > Note: each of these commands should be executed inside the `Mlos.Agent.Server` execution environment (e.g. inside the docker container). From 2cf444d6f526fe9d8f26cae492e528c88b1f3dd7 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 21 Sep 2020 15:50:06 -0500 Subject: [PATCH 9/9] allow browsing some details about the examples on the github io pages as well --- documentation/RepoOrganization.md | 2 +- source/Examples/README.md | 4 ++++ source/Examples/SmartCache/README.md | 4 ++-- source/Examples/SmartSharedChannel/README.md | 24 ++++++++++++++++++++ 4 files changed, 31 insertions(+), 3 deletions(-) create mode 100644 source/Examples/README.md create mode 100644 source/Examples/SmartSharedChannel/README.md diff --git a/documentation/RepoOrganization.md b/documentation/RepoOrganization.md index 9779ffbf210..2aa310d59a4 100644 --- a/documentation/RepoOrganization.md +++ b/documentation/RepoOrganization.md @@ -9,7 +9,7 @@ Some notes on the directory layout organization in this repo. > Note: For this reason, `cmake` output is redirected to `out/cmake/{Release,Debug}/` instead. - [`source/`](../source/#mlos-github-tree-view) contains a directory for each component of MLOS, including unit test source code. - i.e. running `msbuild` or `make` in the `source/` directory will build (and generally analyze) all of the projects, but not execute their tests. - - [`source/Examples/`](../source/Examples/#mlos-github-tree-view) contains sample target codes to optimize with the other MLOS components and help describe the integration methods + - [`source/Examples/`](../source/Examples/) contains sample target codes to optimize with the other MLOS components and help describe the integration methods - [`test/`](../test/#mlos-github-tree-view) contains a directory and project to invoke each of the unit tests. - i.e. running `msbuild` or `make` in the `test/` directory will also run all of the tests. - [`scripts/`](../scripts/#mlos-github-tree-view) contains some helper scripts to initialize development environments, install tools, invoke build pipelines, run tests, etc. diff --git a/source/Examples/README.md b/source/Examples/README.md new file mode 100644 index 00000000000..04b510c083e --- /dev/null +++ b/source/Examples/README.md @@ -0,0 +1,4 @@ +# Examples + +- [SmartCache](./SmartCache/) +- [SmartSharedChannel](./SmartSharedChannel/) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md index b44dc62de70..6a7211ac804 100644 --- a/source/Examples/SmartCache/README.md +++ b/source/Examples/SmartCache/README.md @@ -1,8 +1,8 @@ -# SmartCache Example +# [SmartCache Example](./#mlos-github-tree-view) TODO: Some description of the example contained in this directory. -This `SmartCache` can be used to demonstrate a full end-to-end MLOS integrated microbenchmark for a "smart" component (in this case a cache). +This [`SmartCache`](./#mlos-github-tree-view) can be used to demonstrate a full end-to-end MLOS integrated microbenchmark for a "smart" component (in this case a cache). ## Overview diff --git a/source/Examples/SmartSharedChannel/README.md b/source/Examples/SmartSharedChannel/README.md new file mode 100644 index 00000000000..b7e3d1cd478 --- /dev/null +++ b/source/Examples/SmartSharedChannel/README.md @@ -0,0 +1,24 @@ +# [SmartSharedChannel Example](./#mlos-github-tree-view) + +This [SmartSharedChannel](./#mlos-github-tree-view) example demonstrates a using a microbenchmark of the MLOS shared memory channel to tune the MLOS shared memory channel itself. + +Here are some brief instructions on how to try it out: + +## Building + +1. Build the docker image +2. Create a docker image instance +3. Build the code: + + ```sh + make -C source/Mlos.Agent.Server + make -C source/Examples/SmartSharedChannel + ``` + +## Executing + +```sh +export MLOS_SETTINGS_REGISTRY_PATH=out/dotnet/source/Mlos.UnitTest/Mlos.UnitTest.SettingsRegistry/obj/AnyCPU:out/dotnet/source/Examples/SmartSharedChannel/SmartSharedChannel.SettingsRegistry/obj/AnyCPU + +./tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll out/cmake/Release/source/Examples/SmartSharedChannel/SmartSharedChannel +```