SmartCache example docs

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:
 <https://visualstudio.microsoft.com/vs/community/>
 
 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.

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.

source/Examples/README.md

@@ -0,0 +1,4 @@
+# Examples
+
+- [SmartCache](./SmartCache/)
+- [SmartSharedChannel](./SmartSharedChannel/)

source/Examples/SmartCache/README.md

@@ -0,0 +1,138 @@
+# [SmartCache Example](./#mlos-github-tree-view)
+
+TODO: Some description of the example contained in this directory.
+
+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
+
+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/#mlos-github-tree-view) and [`Mlos.NetCore`](../../Mlos.NetCore/#mlos-github-tree-view) libraries.
+
+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#mlos-github-tree-view) to store and track those experiments.
+
+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#mlos-github-tree-view) 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
+    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 default), 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
+
+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"
+
+tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll \
+    out/cmake/Release/source/Examples/SmartCache/SmartCache
+```
+
+> 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
+...
+```
+
+### Explanation
+
+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.
+
+In this case, `Mlos.Agent.Server` itself starts the component.
+
+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.
+
+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
+    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
+    ```
+
+    > Note: each of these commands should be executed inside the `Mlos.Agent.Server` execution environment (e.g. inside the docker container).

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
+```