You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/en/docs/monolake/Architecture/context.md
+1-2
Original file line number
Diff line number
Diff line change
@@ -2,10 +2,9 @@
2
2
title: "Context Management"
3
3
linkTitle: "Context"
4
4
weight: 4
5
-
description: "Deep dive into Monolake's io_uring-based runtime and performance characteristics compared to traditional event-based runtimes"
6
5
---
7
6
8
-
# Context Management with `certain_map`
7
+
# `certain_map`
9
8
10
9
In a service-oriented architecture, managing the context data that flows between different services is a critical aspect of the system design. The [`certain_map`](https://docs.rs/certain-map/latest/certain_map/) crate provides a powerful way to define and work with typed context data, ensuring the existence of required information at compile-time.
Copy file name to clipboardExpand all lines: content/en/docs/monolake/Architecture/runtime.md
+5-4
Original file line number
Diff line number
Diff line change
@@ -20,15 +20,16 @@ One of the defining characteristics of Monoio is its thread-per-core architectur
20
20
When working with asynchronous I/O in Rust, understanding the underlying mechanisms of different runtimes is crucial. Two prominent approaches are the io-uring-based runtimes(Monolake) and the traditional event notification based runtimes (Tokio, async-std) which use mechanisms like kequeue and epoll. The fundamental difference between these two models lies in how they manage resource ownership and I/O operations.
21
21
22
22
io_uring operates on a submission-based model, where the ownership of resources (such as buffers) is transferred to the kernel upon submission of an I/O request. This model allows for high performance and reduced context switching, as the kernel can process the requests asynchronously. When an I/O operation is completed, the ownership of the buffers is returned to the caller. This ownership transfer leads to several implications:
23
-
1. Ownership Semantics: In io-uring, since the kernel takes ownership of the buffers during the operation, it allows for more efficient memory management. The caller does not need to manage the lifecycle of the buffers while the operation is in progress.
24
23
25
-
2. Concurrency Model: The submission-based model allows for a more straightforward handling of concurrency, as multiple I/O operations can be submitted without waiting for each to complete. This can lead to improved throughput, especially in I/O-bound applications.
24
+
1.**Ownership Semantics**: In io-uring, since the kernel takes ownership of the buffers during the operation, it allows for more efficient memory management. The caller does not need to manage the lifecycle of the buffers while the operation is in progress.
25
+
26
+
2.**Concurrency Model**: The submission-based model allows for a more straightforward handling of concurrency, as multiple I/O operations can be submitted without waiting for each to complete. This can lead to improved throughput, especially in I/O-bound applications.
26
27
27
28
In contrast, Tokio employs systems like kequeue and epoll. In this model, the application maintains ownership of the buffers throughout the lifetime of the I/O operation. Instead of transferring ownership, Tokio merely borrows the buffers, which has several implications:
28
29
29
-
1. Buffer Management: Since Tokio borrows buffers, the application is responsible for managing their lifecycle. This can introduce complexity, especially when dealing with concurrent I/O operations, as developers must ensure that buffers are not inadvertently reused while still in use.
30
+
1.**Buffer Management**: Since Tokio borrows buffers, the application is responsible for managing their lifecycle. This can introduce complexity, especially when dealing with concurrent I/O operations, as developers must ensure that buffers are not inadvertently reused while still in use.
30
31
31
-
2. Polling Mechanism: The polling model in Tokio requires the application to actively wait for events, which can result in increased context switches and potentially less efficient use of system resources compared to the submission-based model of io-uring.
32
+
2.**Polling Mechanism**: The polling model in Tokio requires the application to actively wait for events, which can result in increased context switches and potentially less efficient use of system resources compared to the submission-based model of io-uring.
The Service pattern is a fundamental abstraction in network programming, popularized by the Tower library in the Rust ecosystem. At its core, a Service represents an asynchronous function that processes requests and returns responses. This pattern is particularly powerful for building networking applications as it enables:
Copy file name to clipboardExpand all lines: content/en/docs/monolake/Getting Started/_index.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ description: "This page provides a quick start guide for setting up and running
8
8
9
9
## Prerequisites
10
10
11
-
-**Linux Kernel Support**: IO-uring requires a Linux kernel version that has io_uring support. Generally, kernel versions 5.1 and above provide the necessary support. Ensure that your target system has an appropriate kernel version installed. Monolake will fall back to epoll on Mac OS.
11
+
-**Linux Kernel Support**: io_uring requires linux kernel support. Generally, kernel versions 5.1 and above provide the necessary support. Ensure that your target system has an appropriate kernel version installed. Monolake will fall back to epoll on Mac OS.
12
12
-**Rust nightly**: See the "Rust installation section" below
@@ -57,15 +50,11 @@ Change packet size with a fixed concurrency of 100.
57
50
58
51
| Crate | Description |
59
52
|-------|-------------|
60
-
|[monoio-transports](https://github.com/monoio-rs/monoio-transports)| A foundational crate that provides high-performance, modular networking capabilities, including connectors and utilities for efficient network communications |
61
-
|[service-async](https://github.com/ihciah/service-async)| A foundational crate that introduces a refined Service trait with efficient borrowing and zero-cost abstractions, as well as utilities for service composition and state management |
62
-
|[certain-map](https://github.com/ihciah/certain-map)| A foundational crate that provides a typed map data structure, ensuring the existence of specific items at compile-time, useful for managing data dependencies between services |
|[monoio-http](https://github.com/monoio-rs/monoio-http)| Monoio native, io_uring compatible HTTP/1.1 and HTTP/2 implementation |
65
-
|[monoio-nativetls](https://github.com/monoio-rs/monoio-tls)| The native-tls implementation compatible with monoio |
66
-
|[monoio-rustls](https://github.com/monoio-rs/monoio-tls)| The rustls implementation compatible with monoio |
67
-
68
-
## Blogs
69
-
70
-
-[Monolake: How ByteDance Developed Its Own Rust Proxy to Save Hundreds of Thousands of CPU Cores](TODO)
71
-
-[Monolake open source summit](TODO)
53
+
|[monoio-transports](https://crates.io/crates/monoio-transports)| A foundational crate that provides high-performance, modular networking capabilities, including connectors and utilities for efficient network communications |
54
+
|[service-async](https://crates.io/crates/service-async)| A foundational crate that introduces a refined Service trait with efficient borrowing and zero-cost abstractions, as well as utilities for service composition and state management |
55
+
|[certain-map](https://crates.io/crates/certain-map)| A foundational crate that provides a typed map data structure, ensuring the existence of specific items at compile-time, useful for managing data dependencies between services |
In this guide, we'll walk through the process of implementing a HTTP routing service using the [monolake-services](TODO) crate. This service will handle incoming HTTP requests and route them to appropriate upstream servers based on the configured routes and their associated endpoints.
8
+
In this guide, we'll walk through the process of implementing an HTTP routing service using the `monolake-services` crate. This service will handle incoming HTTP requests and route them to appropriate upstream servers based on the configured routes and their associated endpoints.
Copy file name to clipboardExpand all lines: content/en/docs/monolake/Tutorial/config.md
+2-4
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ description: "This doc covers how to manage configuration and context"
9
9
10
10
When building a service-oriented application using the `monolake-services` crate, you'll need to define the necessary configuration fields in your main `ServerConfig` struct. These fields will be used by the service factories to construct the services that make up your application.
11
11
12
-
The specific fields you'll need to add will depend on the services you're using. For example, if you're implementing a routing HTTP service, you'll need to add a routes field to hold the routing configuration.
12
+
The specific fields you'll need to add will depend on the services you're using. For example, if you're implementing a routing HTTP service, you'll probably want to add a routes field to hold the routing configuration.
13
13
14
14
To configure the routing service, you'll need to add the routes field to your `ServerConfig` struct. This field will hold the RouteConfig structures that define the routing rules.
15
15
```rust
@@ -51,9 +51,7 @@ certain_map::certain_map! {
51
51
}
52
52
```
53
53
54
-
In this example, the Context struct has a single field: peer_addr of type PeerAddr. The #[empty(EmptyContext)] and #[full(FullContext)] attributes define the type aliases for the empty and full versions of the context, respectively.
55
-
56
-
It's important to note that the fields in the Context struct should correspond to the data that the `RoutingHandler` service expects to be available. In this case, the RoutingHandler requires the peer_addr information to be set in the context.
54
+
In this example, the Context struct has a single field: peer_addr of type `PeerAddr`. It's important to note that the fields in the Context struct should correspond to the data that the `RoutingHandler` service expects to be available. In this case, the RoutingHandler requires the peer_addr information to be set in the context.
57
55
58
56
By defining the Context using the certain_map crate, you can ensure that the necessary data is available at compile-time, preventing runtime errors and simplifying the implementation of your services.
Copy file name to clipboardExpand all lines: content/en/docs/monolake/Tutorial/service.md
+1-3
Original file line number
Diff line number
Diff line change
@@ -4,8 +4,6 @@ linkTitle: "Creating Service and Factory"
4
4
weight: 2
5
5
---
6
6
7
-
## Prerequisites
8
-
For a better
9
7
## Defining the Service and Factory
10
8
The `RoutingHandlerFactory` is responsible for creating and updating the `RoutingHandler` service instances. This factory implements the AsyncMakeService trait, allowing it to be used in a FactoryStack for service composition.
11
9
@@ -57,7 +55,7 @@ In this implementation, the RoutingHandlerFactory takes two parameters:
57
55
58
56
The AsyncMakeService implementation for the RoutingHandlerFactory defines how to create a new RoutingHandler instance. It first creates a Router from the configured RouteConfig instances, and then creates the RoutingHandler by calling the make_via_ref method in the inner service factory.
59
57
60
-
Note that in this case, we don't rely on any state from the previous RoutingHandler instance, as the routing configuration is fully defined by the RouteConfig instances. If the inner service factory had some stateful resources (like a connection pool) that needed to be preserved, we could clone those resources when creating the new RoutingHandler.
58
+
Note that in this case, we don't rely on any state from the previous RoutingHandler instance, as the routing configuration is fully defined by the RouteConfig instances. If the inner service factory had some stateful resources (like a connection pool) that needed to be preserved, we could clone those resources when creating the new RoutingHandler. For a more detailed example involving resource transfer, see [UpstreamHandler](https://github.com/cloudwego/monolake/blob/fd2cbe1a8708c379d6355b3cc979540ec49fdb4f/monolake-services/src/http/handlers/upstream.rs#L338), which involves transfer of a HTTP connection pool from the previous UpstreamHandler instance.
61
59
62
60
To integrate the `RoutingHandler` into a service stack, we can use the layer function provided by the `RoutingHandler` type:
description: "This page provides a quick start guide for setting up and running Monolake"
7
+
---
8
+
9
+
## Prerequisites
10
+
11
+
-**Linux Kernel Support**: IO-uring requires a Linux kernel version that includes IO-uring support. Generally, kernel versions 5.1 and above provide the necessary support. Ensure that your target system has an appropriate kernel version installed. Monolake will fall back to epoll on Mac OS.
12
+
-**Rust nightly**: See the "Rust installation section" below
13
+
14
+
## Quick Start
15
+
16
+
This chapter will get you started with Monolake using a simple example config
17
+
18
+
### Rust installation
19
+
20
+
To download and install Rust, and set `rustup` to nightly, you can follow these instructions:
21
+
22
+
1. Download and install Rust by running the following command in your terminal:
23
+
24
+
```markup
25
+
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
26
+
```
27
+
28
+
This command will download the Rust installation script and initiate the installation process.
29
+
30
+
3. Close the terminal and open a new terminal window to ensure the changes take effect.
31
+
32
+
4. Set `rustup` to nightly by running the following command:
33
+
34
+
```markup
35
+
$ rustup default nightly
36
+
```
37
+
38
+
This command sets the default Rust toolchain to the nightly version.
39
+
40
+
5. Verify the installation and check the Rust version by running:
41
+
42
+
```markup
43
+
$ rustc --version
44
+
```
45
+
46
+
This command will display the installed Rust version, which should now be set to nightly.
47
+
48
+
### Setup an HTTP upstream server
49
+
50
+
1.**Install Nginx**: Install Nginx using the package manager of your Linux distribution.
51
+
52
+
2.**Start Nginx**: Start Nginx using the following command:
53
+
54
+
```shell
55
+
sudo service nginx start
56
+
```
57
+
58
+
3.**Configure Port**: Open the Nginx configuration file using a text editor:
59
+
60
+
```shell
61
+
sudo nano /etc/nginx/nginx.conf
62
+
```
63
+
64
+
Inside the file, locate the `http` block and add or modify the `listen` directive to use port 9080:
65
+
66
+
```nginx
67
+
http {
68
+
...
69
+
server {
70
+
listen 9080;
71
+
...
72
+
}
73
+
...
74
+
}
75
+
```
76
+
77
+
Save the changes and exit the text editor.
78
+
79
+
4.**Restart Nginx**: Restart Nginx for the changes to take effect:
80
+
81
+
```shell
82
+
sudo service nginx restart
83
+
```
84
+
85
+
### Build Monolake
86
+
87
+
1. Clone the monolake repository `git clone https://github.com/cloudwego/monolake.git`.
88
+
2. Build the binary:
89
+
90
+
```markup
91
+
$ cargo build --release
92
+
```
93
+
3. Generate the certificates
94
+
```markup
95
+
$ sh examples/gen_cert.sh
96
+
```
97
+
### Run the example
98
+
1. Make sure your endpoints are up and certificates are generated
0 commit comments