mirror of
https://github.com/Tencent/flare.git
synced 2026-10-17 04:41:22 +08:00
docs(readme): update for C++20 + macOS support, retranslate zh/en (#172)
* docs(readme): update for C++20 + macOS support, retranslate zh/en Bring both READMEs in line with the project's current state: * C++ badge upgraded from a generic ``C++`` to ``C++20`` to match the actual standard the project compiles with (``-std=gnu++2a``). * Platform badge upgraded from ``linux`` to ``linux | macOS`` -- macOS port landed in #158, CI matrix in #167 onwards. * Features section: drop the historical ``C++11/14/17/2a`` mix in favor of just ``C++20`` (the standard is committed; the staged adoption is no longer informative for a new reader). * System Requirements section split into ``Linux`` and ``macOS`` subsections, each listing the supported kernel/OS and the minimum toolchain that ships ``std::atomic<T>::wait`` / ``notify_*``: - Linux: GCC 11+ (libstdc++ added the operations in 11.1, per P1135 -- exposed locally on flare/fiber/detail/scheduling_group after the futex path went away in #158). - macOS: 13 (Ventura) or later with Apple Clang from Xcode 14+ (its libc++ has the matching runtime symbols). Also calls out aarch64 / arm64 / x86_64 explicitly. * Retranslated the zh README to read more like native Chinese -- the previous version had several literal-translation-isms ("吸收先前服务 框架"... etc.). Cross-checked the en against the zh and rewrote several en sentences that drifted out of step over the years (badge alt text, "out of the box" phrasing, the third-party tarball blurb, etc.). Both files now describe the same project in the same shape. * Added a back-link from the en README to the zh one (was one-way before). * Updated the blade-build link from chen3feng/blade-build to blade-build/blade-build (org moved). * Fixed bazel/support/README.md link typo (was REAMD.md). No code changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: fix two markdown-link-check failures surfaced by the README PR * Rename `bazel/support/REAMD.md` -> `bazel/support/README.md`. The file has carried the swapped-letter spelling since 2023; the previous README link pointed at the typo'd name, so it was working by accident. The README rewrite in this PR pointed at the canonical spelling and surfaced that the file on disk was wrong. * Add `.github/markdown-link-check-config.json` to suppress the spurious "Status: 0" failure for `https://bazel.build`. The site returns a valid 200 to a normal browser and to `curl`, but apparently UA-filters the markdown-link-check action -- the action reads Status 0 and counts it as broken. Listed it in `ignorePatterns`; wired the config into the existing `gaurav-nelson/github-action-markdown-link-check@v1` invocation via the documented `config-file` input. Also bumps `retryOn429` (small reliability win when the action hits rate limits) and pins the success set to 200/206. Both surfaced by CI on this PR; no other changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
CHEN Feng
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"ignorePatterns": [
|
||||
{
|
||||
"pattern": "^https?://bazel\\.build",
|
||||
"comment": "Apparently UA-filtering markdown-link-check; returns status 0 to the action even though curl from a normal client gets 200. Verified manually."
|
||||
}
|
||||
],
|
||||
"retryOn429": true,
|
||||
"aliveStatusCodes": [200, 206]
|
||||
}
|
||||
@@ -15,3 +15,4 @@ jobs:
|
||||
with:
|
||||
use-quiet-mode: 'yes'
|
||||
check-modified-files-only: 'yes'
|
||||
config-file: '.github/markdown-link-check-config.json'
|
||||
|
||||
+59
-64
@@ -1,88 +1,83 @@
|
||||
# Flare Backend Service Framework
|
||||
|
||||
[中文文档](README.md)
|
||||
|
||||
[](LICENSE)
|
||||
[](https://isocpp.org/)
|
||||
[](https://isocpp.org/)
|
||||
[](https://google.github.io/styleguide/cppguide.html)
|
||||
[](https://www.kernel.org/)
|
||||
[](#system-requirements)
|
||||
|
||||
[Tencent Ads](https://e.qq.com/ads/) is one of the most important businesses of Tencent, and its backend is heavily
|
||||
developed in C++.
|
||||
[Tencent Ads](https://e.qq.com/ads/) is one of the most important businesses at Tencent, with a backend heavily developed in C++.
|
||||
|
||||
Flare is a modern back-end service development framework developed by us based on years of experience, popular open
|
||||
source projects and the latest research results. It aims to provide easy-to-use, high-performance, and stable service
|
||||
development capabilities in the current mainstream software and hardware environment.
|
||||
Flare is a modern backend service development framework, built on the experience of our in-house service frameworks, popular open-source projects, and the latest research. It aims to provide easy-to-use, high-performance, and stable service-development capabilities for today's mainstream software and hardware environments.
|
||||
|
||||
The Flare project started in 2019 and is now widely used in many backend services of Tencent Ads, with tens of
|
||||
thousands of running instances, and has been tested on real production systems.
|
||||
The Flare project started in 2019 and is now widely used across Tencent Ads' backend services, with tens of thousands of running instances battle-tested in real production systems.
|
||||
|
||||
In May 2021, Flare was officially open-sourced to the public to give back to the community and share technology.
|
||||
|
||||
More documents are being translated to English.
|
||||
In May 2021, Flare was officially open-sourced, in the spirit of giving back to the community and sharing what we've learned.
|
||||
|
||||
## Features
|
||||
|
||||
- Modern C++ design style with extensive adoption of new syntax features and standard libraries from C++11/14/17/2a
|
||||
- Provides [M:N thread model](https://en.wikipedia.org/wiki/Thread_(computing)) micro-threaded implementation of
|
||||
[Fiber](flare/doc/fiber.md) for business developers to write high-performance asynchronous calls code with convenient
|
||||
synchronous calls syntax code
|
||||
- Message based [streaming RPC](flare/doc/streaming-rpc.md) support
|
||||
- In addition to RPC, a series of convenient [base libraries](flare/base) are provided, such as string, time and date,
|
||||
encoding processing, compression, encryption and decryption, configuration, HTTP client, etc., which are convenient to
|
||||
get started developing business code quickly
|
||||
- Provides a flexible expansion mechanism. Easy to support multiple protocols, service discovery, load balancing,
|
||||
monitoring and alerting, [RPC tracing](flare/doc/tracing.md), etc.
|
||||
- Extensive optimizations for modern architectures. For example, the [scheduling group](flare/doc/scheduling-group.md) and
|
||||
[object pool](flare/doc/object-pool.md) of [NUMA aware](https://en.wikipedia.org/wiki/Non-uniform_memory_access),
|
||||
[zero-copy buffer](flare /doc/buffer.md), etc.
|
||||
- High-quality code. Strict adherence to [Google C++ Code Specification](https://google.github.io/styleguide/cppguide.html),
|
||||
with 80% test coverage
|
||||
- Complete [documentation](flare/doc) and [examples](flare/example) and [debugging support](flare/doc/debugging.md),
|
||||
easy to get started quickly
|
||||
- Modern C++ style — full adoption of C++20 syntax features and the C++20 standard library.
|
||||
- An [M:N thread model](https://en.wikipedia.org/wiki/Thread_(computing)) user-space [Fiber](flare/doc/fiber.md) implementation, so business code can be written with synchronous syntax while keeping asynchronous performance.
|
||||
- Message-based [streaming RPC](flare/doc/streaming-rpc.md).
|
||||
- In addition to RPC, a set of convenient [base libraries](flare/base): strings, time and date, encoding, compression, encryption, configuration, an HTTP client, and more — designed to get you productive quickly.
|
||||
- A flexible extension mechanism for additional protocols, service discovery, load balancing, monitoring and alerting, [RPC tracing](flare/doc/tracing.md), and more.
|
||||
- Extensive optimizations for modern hardware: [NUMA-aware](https://en.wikipedia.org/wiki/Non-uniform_memory_access) [scheduling groups](flare/doc/scheduling-group.md), [object pools](flare/doc/object-pool.md), [zero-copy buffers](flare/doc/buffer.md), etc.
|
||||
- High-quality code. Strictly follows the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html), with around 80% test coverage.
|
||||
- Comprehensive [documentation](flare/doc), [examples](flare/example), and [debugging support](flare/doc/debugging.md), so you can get started quickly.
|
||||
|
||||
## System Requirements
|
||||
|
||||
- Linux 3.10 kernel or above, no other OS supported at this time
|
||||
- x86-64 processors, aarch64 and ppc64le are also supported, but have not been used in production environment
|
||||
- GCC 8 or above compiler
|
||||
### Linux
|
||||
|
||||
- Linux kernel 3.10 or later.
|
||||
- GCC 11 or later — this is the first libstdc++ version with `std::atomic<T>::wait` / `notify_*` (see [P1135](https://wg21.link/p1135)).
|
||||
- x86-64 processors. aarch64 and ppc64le are also supported but have not been used in production.
|
||||
|
||||
### macOS
|
||||
|
||||
- macOS 13 (Ventura) or later.
|
||||
- Apple Clang — Xcode 14+ ships a libc++ with the runtime symbols for `std::atomic<T>::wait` / `notify_*`.
|
||||
- Apple Silicon (arm64) and Intel (x86_64) are both supported.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Flare comes out of the box with the required [third-party libraries](thirdparty/), so there is usually no need to install additional dependent libraries. Just pull the code and use it under Linux.
|
||||
Flare is "batteries included" — all required [third-party libraries](thirdparty/) ship in-tree, so no additional dependency installation is normally needed.
|
||||
|
||||
The tarball under `thirdparty/` were stored via [Git LFS](https://git-lfs.github.com/), so you need to make sure that `git-lfs` is properly installed before pulling the code.
|
||||
Source tarballs under `thirdparty/` are stored via [Git LFS](https://git-lfs.github.com/), so make sure `git-lfs` is properly installed before cloning.
|
||||
|
||||
### Building
|
||||
|
||||
We use [`blade`](https://github.com/chen3feng/blade-build) to build this project.
|
||||
We use [`blade`](https://github.com/blade-build/blade-build) for day-to-day development:
|
||||
|
||||
- Compile: `./blade build ...`.
|
||||
- Test: `./blade test ...`.
|
||||
- Compile: `./blade build ...`
|
||||
- Test: `./blade test ...`
|
||||
|
||||
After that, you can refer to the introduction in [Getting Started Guide](flare/doc/intro-rpc.md) to build a simple RPC service.
|
||||
Flare also supports [`bazel`](https://bazel.build) as a build system — see [bazel support](bazel/support/README.md).
|
||||
|
||||
After that, follow the [Getting Started Guide](flare/doc/intro-rpc.md) to bring up a simple RPC service.
|
||||
|
||||
### Debugging
|
||||
|
||||
We believe that the [debugging](flare/doc/debugging.md) experience is also an important part of the development and maintenance process, and we have made some support for this as follows.
|
||||
We treat [debugging experience](flare/doc/debugging.md) as a first-class concern of day-to-day maintenance, and ship the following out of the box:
|
||||
|
||||
- [GDB plugin for listing pending fibers](flare/doc/gdb-plugin.md)
|
||||
- [A GDB plugin that lists suspended fibers](flare/doc/gdb-plugin.md)
|
||||
- [Support for various Sanitizers](flare/doc/sanitizers.md)
|
||||
|
||||
### Testing
|
||||
|
||||
To improve the experience of writing tests, we provide a number of tools for [writing tests](flare/doc/testing.md).
|
||||
|
||||
These include, but are not limited to:
|
||||
To improve the experience of writing unit tests, we provide a set of [testing utilities](flare/doc/testing.md), including but not limited to:
|
||||
|
||||
- [RPC Mock](flare/testing/rpc_mock.h)
|
||||
- [Redis Mock](flare/testing/redis_mock.h)
|
||||
- [COS Mock](flare/testing/cos_mock.h)
|
||||
- [HTTP Mock](flare/testing/http_mock.h)
|
||||
- [Non-virtual Function Mock](flare/testing/hooking_mock.h)
|
||||
- Some tool methods, etc.
|
||||
- [Non-virtual function Mock](flare/testing/hooking_mock.h)
|
||||
- And several helper utilities.
|
||||
|
||||
### Example
|
||||
|
||||
We provided some [examples](flare/example) for reference, the following code snippet is a simple relay service (include both client and service).
|
||||
We've put together several [examples](flare/example) for reference. The snippet below is a simple relay service that exercises both the RPC client and server sides:
|
||||
|
||||
```cpp
|
||||
#include "gflags/gflags.h"
|
||||
@@ -142,13 +137,13 @@ int main(int argc, char** argv) {
|
||||
}
|
||||
```
|
||||
|
||||
With the builtin [M:N user mode thread](flare/doc/fiber.md) support, requesting outside services from flare with synchronous syntax and using the synchorous inteface of our [builtin clients for many popular protocols](flare/net) will not incur peforrmance penalty. For more complex concurrency or synchronous requirements, please refer the [document](flare/doc/fiber.md) for details.
|
||||
Flare is built on top of [M:N user-space threads](flare/doc/fiber.md), so synchronous requests to external services through Flare — and the synchronous interfaces of [Flare's built-in clients](flare/net) — don't carry a performance penalty. For more complex concurrent or asynchronous needs, see the [Fiber documentation](flare/doc/fiber.md).
|
||||
|
||||
Besides, the example `*.flare.pb.h` is generated by [our Protocol Buffers plugin](flare/doc/pb-plugin.md). The interfaces generated this way are easier to use compared to the ones generated by Protocol Buffers' `cc_generic_services`
|
||||
Note also that the `*.flare.pb.h` in the example is generated by [Flare's Protocol Buffers plugin](flare/doc/pb-plugin.md). Compared to Protocol Buffers' own `cc_generic_services`, the resulting interfaces are easier to use.
|
||||
|
||||
## More Complex Examples
|
||||
## A More Complex Example
|
||||
|
||||
In practice you will often face scenarios where you need to request multiple backends concurrently, and the following example shows you how to do this with Flare.
|
||||
In real use, you'll often want to fan out concurrent requests to multiple backends. The example below shows how to do that with Flare:
|
||||
|
||||
```cpp
|
||||
// For illustration purpose only. Normally you wouldn't want to declare them as
|
||||
@@ -186,30 +181,30 @@ void FancyServiceImpl::FancyJob(const FancyJobRequest& request,
|
||||
}
|
||||
```
|
||||
|
||||
In this example, we:
|
||||
In this example we:
|
||||
|
||||
- Initiated three asynchronous requests via three different clients ([HTTP](flare/net/http/http_client.h), [Tencent Cloud COS](flare/net/cos/cos_client.h), RPC).
|
||||
- Waiting for all requests to complete synchronously via `flare::fiber::BlockingGet`. Here we only block the user mode thread and there are no performance issues.
|
||||
- Print logs to output the response of each service.
|
||||
- Issue three asynchronous requests through three different clients ([HTTP](flare/net/http/http_client.h), [Tencent Cloud COS](flare/net/cos/cos_client.h), and RPC).
|
||||
- Wait for all of them with `flare::fiber::BlockingGet` — this only blocks the user-space thread, so there's no performance issue.
|
||||
- Log the response from each service.
|
||||
|
||||
For demonstration purposes, we are requesting three heterogeneous services here. You can also request homogeneous, or partially homogeneous and partially heterogeneous services in this way if necessary.
|
||||
For demonstration purposes we requested three heterogeneous services here, but you can use the same pattern for homogeneous, or partially homogeneous and partially heterogeneous, backends.
|
||||
|
||||
## Contribution
|
||||
## Contributing
|
||||
|
||||
For developers who want to learn more about the internal design of Flare, or who want to participate the development of Flare, more documentation can be found under under [`flare/doc/`](flare/doc/).
|
||||
Contributions are very welcome. Developers interested in Flare's internals, or those who want to fork and extend it, will find more technical documentation under [`flare/doc/`](flare/doc/).
|
||||
|
||||
Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
|
||||
|
||||
## Performance
|
||||
|
||||
Due to the characteristics of the business requirements, we prefer to optimize the smoothness of latency and jitter rather than throughput in the design process, but also try to ensure performance under this premise.
|
||||
Because of the nature of our workload, our design leans towards optimizing latency and its stability rather than raw throughput — while still keeping performance reasonable under that constraint.
|
||||
|
||||
For simple comparison purposes, we have provided [preliminary performance data](flare/doc/benchmark.md).
|
||||
For a simple side-by-side comparison, see the [preliminary performance numbers](flare/doc/benchmark.md).
|
||||
|
||||
## Credits
|
||||
|
||||
- Our underlying implementation draws heavily on the design of [brpc](https://github.com/apache/incubator-brpc).
|
||||
- For the RPC part, [grpc](https://grpc.io/) gave us a lot of inspiration.
|
||||
- We rely on a lot of [third party libraries](thirdparty/) from the open source community, standing on the shoulders of giants allows us to develop this project faster and better, and therefore actively give back to the open source community.
|
||||
- Our lower-level implementation draws heavily on the design of [brpc](https://github.com/apache/incubator-brpc).
|
||||
- The RPC layer was inspired by [grpc](https://grpc.io/) in many places.
|
||||
- We rely on a number of [third-party libraries](thirdparty/) from the open-source community. Standing on the shoulders of giants lets us build this project faster and better — and is why we are happy to give back.
|
||||
|
||||
We'd like to express our sincere gratitude and appreciation to them.
|
||||
Our sincere thanks to all of the above.
|
||||
|
||||
@@ -5,75 +5,81 @@ Flare Backend Service Framework
|
||||
[English Document](README-en.md)
|
||||
|
||||
[](LICENSE)
|
||||
[](https://isocpp.org/)
|
||||
[](https://isocpp.org/)
|
||||
[](https://google.github.io/styleguide/cppguide.html)
|
||||
[](https://www.kernel.org/)
|
||||
[](#系统要求)
|
||||
|
||||
[腾讯广告](https://e.qq.com/ads/) 是腾讯公司最重要的业务之一，其后台大量采用 C++ 开发。
|
||||
|
||||
Flare 是我们吸收先前服务框架和业界开源项目及最新研究成果开发的现代化的后台服务开发框架，旨在提供针对目前主流软硬件环境下的易用、高性能、平稳的服务开发能力。
|
||||
Flare 是我们在汲取自研服务框架经验、参考业界开源项目和最新研究成果的基础上，开发的现代化后台服务开发框架。目标是在当今主流软硬件环境下，提供易用、高性能、平稳的服务开发能力。
|
||||
|
||||
Flare 项目开始于 2019 年，目前广泛应用于腾讯广告的众多后台服务，拥有数以万计的运行实例，在实际生产系统上经受了足够的考验。
|
||||
Flare 项目始于 2019 年，目前广泛应用于腾讯广告的各类后台服务，拥有数以万计的运行实例，在生产系统上经受了充分的考验。
|
||||
|
||||
2021 年 5 月，本着回馈社区、技术共享的精神，正式对外开源。
|
||||
2021 年 5 月，我们本着回馈社区、技术共享的精神正式将 Flare 开源。
|
||||
|
||||
## 特点
|
||||
|
||||
- 现代 C++ 设计风格，广泛采用了 C++11/14/17/2a 的新的语法特性和标准库
|
||||
- 提供了 [M:N 的线程模型](https://en.wikipedia.org/wiki/Thread_(computing))的微线程实现[Fiber](flare/doc/fiber.md)，方便业务开发人员以便利的同步调用语法编写高性能的异步调用代码
|
||||
- 支持基于消息的[流式 RPC](flare/doc/streaming-rpc.md)支持
|
||||
- 除了 RPC 外，还提供了一系列便利的[基础库](flare/base)，比如字符串、时间日期、编码处理、压缩、加密解密、配置、HTTP 客户端等，方便快速上手开发业务代码
|
||||
- 提供了灵活的扩充机制。方便支持多种协议、服务发现、负载均衡、监控告警、[调用追踪](flare/doc/tracing.md)等
|
||||
- 针对现代体系结构做了大量的优化。比如 [NUMA 感知](https://en.wikipedia.org/wiki/Non-uniform_memory_access)的[调度组](flare/doc/scheduling-group.md)和[对象池](flare/doc/object-pool.md)、[零拷贝缓冲区](flare/doc/buffer.md)等
|
||||
- 现代 C++ 设计风格，全面采用 C++20 的语法特性和标准库
|
||||
- 提供 [M:N 线程模型](https://en.wikipedia.org/wiki/Thread_(computing)) 的用户态微线程实现 [Fiber](flare/doc/fiber.md)，让开发者用同步调用的写法获得异步调用的性能
|
||||
- 支持基于消息的[流式 RPC](flare/doc/streaming-rpc.md)
|
||||
- 除 RPC 外，还提供了一系列便利的[基础库](flare/base)：字符串、时间日期、编码、压缩、加解密、配置、HTTP 客户端等等，方便快速上手开发业务代码
|
||||
- 提供了灵活的扩展机制，方便支持多种协议、服务发现、负载均衡、监控告警、[调用追踪](flare/doc/tracing.md)等
|
||||
- 针对现代体系结构做了大量优化：[NUMA 感知](https://en.wikipedia.org/wiki/Non-uniform_memory_access)的[调度组](flare/doc/scheduling-group.md)、[对象池](flare/doc/object-pool.md)、[零拷贝缓冲区](flare/doc/buffer.md)等
|
||||
- 高质量的代码。严格遵守 [Google C++ 代码规范](https://google.github.io/styleguide/cppguide.html)，测试覆盖率达 80%
|
||||
- 完善的[文档](flare/doc)和[示例](flare/example)以及[调试支持](flare/doc/debugging.md)，方便快速上手
|
||||
- 完善的[文档](flare/doc)、[示例](flare/example)以及[调试支持](flare/doc/debugging.md)，方便快速上手
|
||||
|
||||
## 系统要求
|
||||
|
||||
- Linux 3.10 或以上内核，暂不支持其他操作系统
|
||||
- x86-64 处理器，也支持 aarch64 及 ppc64le，但是未在生产环境上实际使用过
|
||||
- GCC 8 或以上版本的编译器
|
||||
### Linux
|
||||
|
||||
- Linux 3.10 或以上内核
|
||||
- GCC 11 或以上版本的编译器（最早支持 `std::atomic<T>::wait` / `notify_*` 的 libstdc++ 版本，参见 [P1135](https://wg21.link/p1135)）
|
||||
- x86-64 处理器；aarch64 和 ppc64le 也支持，但未在生产环境实际投入使用
|
||||
|
||||
### macOS
|
||||
|
||||
- macOS 13 (Ventura) 或以上
|
||||
- Apple Clang（Xcode 14 及以上自带的 libc++ 已包含 `std::atomic<T>::wait` / `notify_*` 运行期符号）
|
||||
- Apple Silicon (arm64) 与 Intel (x86_64) 均可
|
||||
|
||||
## 开始使用
|
||||
|
||||
Flare 是开箱即用的，已经自带了所需的[第三方库](thirdparty/)，因此通常不需要额外安装依赖库。只需要在 Linux 下，拉取代码，即可使用。
|
||||
Flare 是开箱即用的，已经自带了所需的[第三方库](thirdparty/)，通常不需要额外安装依赖。
|
||||
|
||||
`thirdparty/`下面的压缩包我们通过[Git LFS](https://git-lfs.github.com/)存储，因此在拉取代码之前您需要确保`git-lfs`已经正确的安装了。
|
||||
`thirdparty/` 下的源码包通过 [Git LFS](https://git-lfs.github.com/) 存储，因此拉取代码前请确保 `git-lfs` 已正确安装。
|
||||
|
||||
### 构建
|
||||
|
||||
我们使用[`blade`](https://github.com/chen3feng/blade-build)进行日常开发。
|
||||
我们使用 [`blade`](https://github.com/blade-build/blade-build) 进行日常开发：
|
||||
|
||||
- 编译：`./blade build ...`，
|
||||
- 测试：`./blade test ...`。
|
||||
- 编译：`./blade build ...`
|
||||
- 测试：`./blade test ...`
|
||||
|
||||
Flare还支持[`bazel`](https://bazel.build)作为构建系统，可以查看[bazel support](bazel/support/REAMD.md)。
|
||||
Flare 也支持 [`bazel`](https://bazel.build) 作为构建系统，参见 [bazel support](bazel/support/README.md)。
|
||||
|
||||
之后就可以参考[入门导引](flare/doc/intro-rpc.md)中的介绍，搭建一个简单的RPC服务了。
|
||||
之后可以参考[入门导引](flare/doc/intro-rpc.md)，搭建一个简单的 RPC 服务。
|
||||
|
||||
### 调试
|
||||
|
||||
我们相信，[调试](flare/doc/debugging.md)体验也是开发维护过程中很重要的一部分，我们为此也做了如下一些支持：
|
||||
我们认为[调试体验](flare/doc/debugging.md)是开发维护过程中很重要的一环，为此提供了：
|
||||
|
||||
- [GDB插件用于列出挂起的fibers](flare/doc/gdb-plugin.md)
|
||||
- [支持各种Sanitizers](flare/doc/sanitizers.md)
|
||||
- [GDB 插件，用于列出挂起的 fiber](flare/doc/gdb-plugin.md)
|
||||
- [对各种 Sanitizers 的支持](flare/doc/sanitizers.md)
|
||||
|
||||
### 测试
|
||||
|
||||
为了改善编写单测的体验，我们提供了一些用于[编写单测的工具](flare/doc/testing.md)。
|
||||
|
||||
这包括但不限于：
|
||||
为改善编写单测的体验，我们提供了一些[测试工具](flare/doc/testing.md)，包括但不限于：
|
||||
|
||||
- [RPC Mock](flare/testing/rpc_mock.h)
|
||||
- [Redis Mock](flare/testing/redis_mock.h)
|
||||
- [COS Mock](flare/testing/cos_mock.h)
|
||||
- [HTTP Mock](flare/testing/http_mock.h)
|
||||
- [非虚函数Mock](flare/testing/hooking_mock.h)
|
||||
- 部分工具方法等
|
||||
- [非虚函数 Mock](flare/testing/hooking_mock.h)
|
||||
- 以及若干工具方法等
|
||||
|
||||
### 示例
|
||||
|
||||
我们提供了一些[使用示例](flare/example)以供参考，下面是一个简单的转发服务（同时包含RPC客户端及服务端的使用）。
|
||||
我们提供了一些[使用示例](flare/example)，下面是一个简单的转发服务（同时演示了 RPC 客户端与服务端的使用）：
|
||||
|
||||
```cpp
|
||||
#include "gflags/gflags.h"
|
||||
@@ -133,13 +139,13 @@ int main(int argc, char** argv) {
|
||||
}
|
||||
```
|
||||
|
||||
Flare内部[基于M:N的用户态线程](flare/doc/fiber.md)实现，因此通过Flare同步的请求外界服务、使用[Flare内置的各种客户端](flare/net)的同步接口均不会导致性能问题。如果有更复杂的并发或异步等需求可以参考[我们的文档](flare/doc/fiber.md)。
|
||||
Flare 内部[基于 M:N 用户态线程](flare/doc/fiber.md)实现，因此通过 Flare 同步请求外部服务、调用 [Flare 内置的各种客户端](flare/net) 的同步接口都不会带来性能问题。如有更复杂的并发或异步需求，可参考 [Fiber 文档](flare/doc/fiber.md)。
|
||||
|
||||
另外，示例中`*.flare.pb.h`通过[我们的Protocol Buffers插件](flare/doc/pb-plugin.md)生成。这样生成的接口相对于Protocol Buffers生成的`cc_generic_services`而言，更易使用。
|
||||
另外，示例中的 `*.flare.pb.h` 通过 [Flare 的 Protocol Buffers 插件](flare/doc/pb-plugin.md) 生成。相对于 Protocol Buffers 原生的 `cc_generic_services`，这种方式生成的接口更易用。
|
||||
|
||||
## 更复杂的示例
|
||||
|
||||
实际使用中，往往会面对需要并发请求多种后端的场景，下面的示例介绍了如何在Flare中进行这种操作：
|
||||
实际使用中往往需要并发请求多种后端，下面的示例展示了如何在 Flare 中实现这种模式：
|
||||
|
||||
```cpp
|
||||
// For illustration purpose only. Normally you wouldn't want to declare them as
|
||||
@@ -179,28 +185,28 @@ void FancyServiceImpl::FancyJob(const FancyJobRequest& request,
|
||||
|
||||
这个示例中，我们：
|
||||
|
||||
- 通过三种不同的客户端（[HTTP](flare/net/http/http_client.h)、[腾讯云COS](flare/net/cos/cos_client.h)、RPC）发起了三个异步请求；
|
||||
- 通过`flare::fiber::BlockingGet`同步等待所有请求完成。这儿我们只会阻塞用户态线程，不会存在性能问题；
|
||||
- 打印日志输出各个服务的响应。
|
||||
- 通过三种不同的客户端（[HTTP](flare/net/http/http_client.h)、[腾讯云 COS](flare/net/cos/cos_client.h)、RPC）发起了三个异步请求
|
||||
- 通过 `flare::fiber::BlockingGet` 同步等待所有请求完成——这里只会阻塞用户态线程，不会有性能问题
|
||||
- 输出日志展示各个服务的响应
|
||||
|
||||
出于展示目的，我们这儿请求了三个异构的服务。如果有必要，也可以通过这种方式请求同构的、或者部分同构部分异构的服务。
|
||||
出于展示目的，这里请求的是三个异构服务。如有需要，也可以用同样的方式请求同构服务、或同构异构混合的服务。
|
||||
|
||||
## 参与开发
|
||||
|
||||
我们非常欢迎参与共同建设，对于希望了解 Flare 更多内部设计的开发者，或需要对 Flare 进行二次开发的开发者而言，[`flare/doc/`](flare/doc/)下有更多的技术文档可供参考。
|
||||
我们非常欢迎共建。希望了解 Flare 更多内部设计的开发者、或需要对 Flare 进行二次开发的开发者，可参考 [`flare/doc/`](flare/doc/) 下的技术文档。
|
||||
|
||||
详情请参考[CONTRIBUTING.md](CONTRIBUTING.md)。
|
||||
详情请参考 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||||
|
||||
## 性能
|
||||
|
||||
由于业务需求的特点，我们在设计过程中更倾向于优化延迟及抖动的平稳性而非吞吐，但是也在这个前提下尽量保证性能。
|
||||
由于业务需求的特点，我们在设计中更倾向于优化延迟及其平稳性，而非吞吐；但在这一前提下也尽力兼顾性能。
|
||||
|
||||
出于简单的对比目的，我们提供了[初步的性能数据](flare/doc/benchmark.md)。
|
||||
简单的对比数据可见[初步性能数据](flare/doc/benchmark.md)。
|
||||
|
||||
## 致谢
|
||||
|
||||
- 我们的底层实现大量参考了[brpc](https://github.com/apache/incubator-brpc)的设计。
|
||||
- RPC部分，[grpc](https://grpc.io/)给了我们很多启发。
|
||||
- 我们依赖了不少开源社区的[第三方库](thirdparty/)，站在巨人的肩膀上使得我们可以更快更好地开发本项目，也因此积极地回馈给开源社区。
|
||||
- 我们的底层实现大量参考了 [brpc](https://github.com/apache/incubator-brpc) 的设计
|
||||
- RPC 部分，[grpc](https://grpc.io/) 给了我们很多启发
|
||||
- 我们依赖了不少来自开源社区的[第三方库](thirdparty/)，正是站在巨人的肩膀上让我们得以更快更好地开发本项目，也因此我们也乐于回馈社区
|
||||
|
||||
在此，我们对上述项目一并致以谢意。
|
||||
在此向上述项目一并致以谢意。
|
||||
|
||||
Reference in New Issue
Block a user