这是 FIDL 示例目录，旨在通过真实软件工作流的简化实现演示 FIDL 概念。
示例索引
以下示例依次演示了实用的 FIDL 概念。
计算器
计算器示例展示了用于创建第一个 FIDL 协议的基本构建块。
键值对存储区
键值对存储区示例演示了如何使用 FIDL 构建简单的键值对存储区，以了解该语言中提供的各种数据类型。
画布
canvas 示例演示了如何使用 FIDL 构建简单的 2D 线渲染画布，以了解常用的数据流模式。
概念索引
上一部分中列出的至少一个示例对 FIDL 语言中的每个“概念”进行了举例说明。以下部分列出了每个此类概念的快速参考及其示例实现。
确认模式
FIDL 配方：确认模式
确认模式是一种简单的流控制方法，适用于单向调用的方法。该方法不会保留为单向调用，而是变为双向调用，并且没有响应，俗称“确认”ack。确认消息存在的唯一原因是告知发送方消息已被接收，发送方可以使用该消息来决定如何进行后续操作。
这种确认的成本会增加在信道上的聊天。如果客户端在继续进行下一个调用之前等待确认，这种模式也会导致性能下降。
来回发送不按流量计费的单向调用会产生简单的设计，但存在潜在问题：如果服务器处理更新的速度比客户端发送的速度慢得多，该怎么办？例如，客户端可能会加载某个文本文件中由数千行组成的绘图，并尝试按顺序发送这些行。我们如何向客户端应用背压，以防止服务器因这一波更新而不堪重负？
通过使用确认模式并将单向调用 AddLine(...); 转换为双向 AddLine(...) -> ();，我们可以向客户端提供反馈。这将允许客户端视情况限制其输出。在此示例中，客户端只需等待确认消息再发送其等待的下一条消息，尽管更复杂的设计可以乐观地发送消息，并且仅在接收异步确认消息的频率低于预期时进行限制。
首先，我们需要定义接口定义和自动化测试框架。FIDL、CML 和 Realm 接口定义设置了一个可供任意实现使用的基架：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.canvas.addlinemetered;
/// A point in 2D space.
type Point = struct {
x int64;
y int64;
};
/// A line in 2D space.
alias Line = array<Point, 2>;
/// A bounding box in 2D space. This is the result of "drawing" operations on our canvas, and what
/// the server reports back to the client. These bounds are sufficient to contain all of the
/// lines (inclusive) on a canvas at a given time.
type BoundingBox = struct {
top_left Point;
bottom_right Point;
};
/// Manages a single instance of a canvas. Each session of this protocol is responsible for a new
/// canvas.
@discoverable
open protocol Instance {
/// Add a line to the canvas.
///
/// This method can be considered an improvement over the one-way case from a flow control
/// perspective, as it is now much more difficult for a well-behaved client to "get ahead" of
/// the server and overwhelm. This is because the client now waits for each request to be acked
/// by the server before proceeding. This change represents a trade-off: we get much greater
/// synchronization of message flow between the client and the server, at the cost of worse
/// performance at the limit due to the extra wait imposed by each ack.
flexible AddLine(struct {
line Line;
}) -> ();
/// Update the client with the latest drawing state. The server makes no guarantees about how
/// often this event occurs - it could occur multiple times per board state, for example.
flexible -> OnDrawn(BoundingBox);
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.canvas.addlinemetered.Instance" },
],
config: {
// A script for the client to follow. Entries in the script may take one of two forms: a
// pair of signed-integer coordinates like "-2,15:4,5", or the string "WAIT". The former
// calls `AddLine(...)`, while the latter pauses execution until the next `->OnDrawn(...)`
// event is received.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use a vector of `union { Point; WaitEnum}`
// here.
script: {
type: "vector",
max_count: 100,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.canvas.addlinemetered.Instance" },
],
expose: [
{
protocol: "examples.canvas.addlinemetered.Instance",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.canvas.addlinemetered.Instance",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{format_err, Context as _, Error},
config::Config,
fidl_examples_canvas_addlinemetered::{InstanceEvent, InstanceMarker, Point},
fuchsia_component::client::connect_to_protocol,
futures::TryStreamExt,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send Instance requests
// across the channel.
let instance = connect_to_protocol::<InstanceMarker>()?;
println!("Outgoing connection enabled");
for action in config.script.into_iter() {
// If the next action in the script is to "WAIT", block until an OnDrawn event is received
// from the server.
if action == "WAIT" {
let mut event_stream = instance.take_event_stream();
loop {
match event_stream
.try_next()
.await
.context("Error getting event response from proxy")?
.ok_or_else(|| format_err!("Proxy sent no events"))?
{
InstanceEvent::OnDrawn { top_left, bottom_right } => {
println!(
"OnDrawn event received: top_left: {:?}, bottom_right: {:?}",
top_left, bottom_right
);
break;
}
InstanceEvent::_UnknownEvent { ordinal, .. } => {
println!("Received an unknown event with ordinal {ordinal}");
}
}
}
continue;
}
// If the action is not a "WAIT", we need to draw a line instead. Parse the string input,
// making two points out of it.
let mut points = action
.split(":")
.map(|point| {
let integers = point
.split(",")
.map(|integer| integer.parse::<i64>().unwrap())
.collect::<Vec<i64>>();
Point { x: integers[0], y: integers[1] }
})
.collect::<Vec<Point>>();
// Assemble a line from the two points.
let from = points.pop().ok_or(format_err!("line requires 2 points, but has 0"))?;
let to = points.pop().ok_or(format_err!("line requires 2 points, but has 1"))?;
let line = [from, to];
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
println!("AddLine request sent: {:?}", line);
// By awaiting on the reply, we prevent the client from sending another request before the
// server is ready to handle, thereby syncing the flow rate between the two parties over
// this method.
instance.add_line(&line).await.context("Error sending request")?;
println!("AddLine response received");
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl::endpoints::RequestStream as _,
fidl_examples_canvas_addlinemetered::{
BoundingBox, InstanceRequest, InstanceRequestStream, Point,
},
fuchsia_async::{Time, Timer},
fuchsia_component::server::ServiceFs,
fuchsia_zircon::{self as zx},
futures::future::join,
futures::prelude::*,
std::sync::{Arc, Mutex},
};
// A struct that stores the two things we care about for this example: the bounding box the lines
// that have been added thus far, and bit to track whether or not there have been changes since the
// last `OnDrawn` event.
#[derive(Debug)]
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
changed: bool,
bounding_box: BoundingBox,
}
impl CanvasState {
/// Handler for the `AddLine` method.
fn add_line(&mut self, line: [Point; 2]) {
// Update the bounding box to account for the new lines we've just "added" to the canvas.
let bounds = &mut self.bounding_box;
for point in line {
if point.x < bounds.top_left.x {
bounds.top_left.x = point.x;
}
if point.y > bounds.top_left.y {
bounds.top_left.y = point.y;
}
if point.x > bounds.bottom_right.x {
bounds.bottom_right.x = point.x;
}
if point.y < bounds.bottom_right.y {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next tick.
self.changed = true
}
}
/// Creates a new instance of the server, paired to a single client across a zircon channel.
async fn run_server(stream: InstanceRequestStream) -> Result<(), Error> {
// Create a new in-memory state store for the state of the canvas. The store will live for the
// lifetime of the connection between the server and this particular client.
let state = Arc::new(Mutex::new(CanvasState {
changed: true,
bounding_box: BoundingBox {
top_left: Point { x: 0, y: 0 },
bottom_right: Point { x: 0, y: 0 },
},
}));
// Take ownership of the control_handle from the stream, which will allow us to push events from
// a different async task.
let control_handle = stream.control_handle();
// A separate watcher task periodically "draws" the canvas, and notifies the client of the new
// state. We'll need a cloned reference to the canvas state to be accessible from the new
// task.
let state_ref = state.clone();
let update_sender = || async move {
loop {
// Our server sends one update per second.
Timer::new(Time::after(zx::Duration::from_seconds(1))).await;
let mut state = state_ref.lock().unwrap();
if !state.changed {
continue;
}
// After acquiring the lock, this is where we would draw the actual lines. Since this is
// just an example, we'll avoid doing the actual rendering, and simply send the bounding
// box to the client instead.
let bounds = state.bounding_box;
match control_handle.send_on_drawn(&bounds.top_left, &bounds.bottom_right) {
Ok(_) => println!(
"OnDrawn event sent: top_left: {:?}, bottom_right: {:?}",
bounds.top_left, bounds.bottom_right
),
Err(_) => return,
}
// Reset the change tracker.
state.changed = false
}
};
// Handle requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
let state_ref = &state;
let request_handler =
stream.map(|result| result.context("failed request")).try_for_each(|request| async move {
// Match based on the method being invoked.
match request {
InstanceRequest::AddLine { line, responder } => {
println!("AddLine request received: {:?}", line);
state_ref.lock().unwrap().add_line(line);
// Because this is now a two-way method, we must use the generated `responder`
// to send an in this case empty reply back to the client. This is the mechanic
// which syncs the flow rate between the client and server on this method,
// thereby preventing the client from "flooding" the server with unacknowledged
// work.
responder.send().context("Error responding")?;
println!("AddLine response sent");
} //
InstanceRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
});
// This await does not complete, and thus the function does not return, unless the server errors
// out. The stream will await indefinitely, thereby creating a long-lived server. Here, we first
// wait for the updater task to realize the connection has died, then bubble up the error.
join(request_handler, update_sender()).await.0
}
// A helper enum that allows us to treat a `Instance` service instance as a value.
enum IncomingService {
Instance(InstanceRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Instance` protocol - this will allow the client to see
// the server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Instance);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Instance(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/add_line_metered/cpp_natural/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::AsyncEventHandler<examples_canvas_addlinemetered::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(fidl::Event<examples_canvas_addlinemetered::Instance::OnDrawn>& event) override {
auto top_left = event.top_left();
auto bottom_right = event.bottom_right();
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y() << " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_addlinemetered::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_addlinemetered::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_addlinemetered::Point(x, y);
}
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
::std::array<::examples_canvas_addlinemetered::Point, 2> ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_addlinemetered::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
auto line = ParseLine(action);
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x() << ", y: " << line[1].y()
<< " }, Point { x: " << line[0].x() << ", y: " << line[0].y() << " }]";
client->AddLine(line).ThenExactlyOnce(
[&](fidl::Result<examples_canvas_addlinemetered::Instance::AddLine>& result) {
// Check if the FIDL call succeeded or not.
if (!result.is_ok()) {
// Check that our two-way call succeeded, and handle the error appropriately. In the
// case of this example, there is nothing we can do to recover here, except to log an
// error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLine request: "
<< result.error_value().FormatDescription();
}
FX_LOGS(INFO) << "AddLine response received";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples_canvas_addlinemetered::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_addlinemetered::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](InstanceImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLine(AddLineRequest& request, AddLineCompleter::Sync& completer) override {
auto points = request.line();
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << points[1].x()
<< ", y: " << points[1].y() << " }, Point { x: " << points[0].x()
<< ", y: " << points[0].y() << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : request.line()) {
if (point.x() < bounds.top_left().x()) {
bounds.top_left().x() = point.x();
}
if (point.y() > bounds.top_left().y()) {
bounds.top_left().y() = point.y();
}
if (point.x() > bounds.bottom_right().x()) {
bounds.bottom_right().x() = point.x();
}
if (point.y() < bounds.bottom_right().y()) {
bounds.bottom_right().y() = point.y();
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
// Because this is now a two-way method, we must use the generated |completer| to send an in
// this case empty reply back to the client. This is the mechanic which syncs the flow rate
// between the client and server on this method, thereby preventing the client from "flooding"
// the server with unacknowledged work.
completer.Reply();
FX_LOGS(INFO) << "AddLine response sent";
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_addlinemetered::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto result = fidl::SendEvent(binding_)->OnDrawn(state_.bounding_box);
if (!result.is_ok()) {
return;
}
auto top_left = state_.bounding_box.top_left();
auto bottom_right = state_.bounding_box.bottom_right();
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y()
<< " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
// Reset the change tracker.
state_.changed = false;
},
after);
}
fidl::ServerBindingRef<examples_canvas_addlinemetered::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.addlinemetered.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_addlinemetered::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++（有线）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/add_line_metered/cpp_wire/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::WireAsyncEventHandler<examples_canvas_addlinemetered::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(fidl::WireEvent<examples_canvas_addlinemetered::Instance::OnDrawn>* event) override {
auto top_left = event->top_left;
auto bottom_right = event->bottom_right;
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_addlinemetered::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_addlinemetered::wire::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_addlinemetered::wire::Point{.x = x, .y = y};
}
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
::fidl::Array<::examples_canvas_addlinemetered::wire::Point, 2> ParseLine(
const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_addlinemetered::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
auto line = ParseLine(action);
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
client->AddLine(line).ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_canvas_addlinemetered::Instance::AddLine>& result) {
// Check if the FIDL call succeeded or not.
if (!result.ok()) {
// Check that our two-way call succeeded, and handle the error appropriately. In the
// case of this example, there is nothing we can do to recover here, except to log an
// error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLine request: " << result.status_string();
}
FX_LOGS(INFO) << "AddLine response received";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples_canvas_addlinemetered::wire::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_addlinemetered::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](InstanceImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLine(AddLineRequestView request, AddLineCompleter::Sync& completer) override {
auto points = request->line;
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : request->line) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
// Because this is now a two-way method, we must use the generated |completer| to send an in
// this case empty reply back to the client. This is the mechanic which syncs the flow rate
// between the client and server on this method, thereby preventing the client from "flooding"
// the server with unacknowledged work.
completer.Reply();
FX_LOGS(INFO) << "AddLine response sent";
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_addlinemetered::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = weak->state_.bounding_box.top_left;
auto bottom_right = weak->state_.bounding_box.bottom_right;
fidl::Status status =
fidl::WireSendEvent(weak->binding_)->OnDrawn(top_left, bottom_right);
if (!status.ok()) {
return;
}
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change tracker.
weak->state_.changed = false;
},
after);
}
fidl::ServerBindingRef<examples_canvas_addlinemetered::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.addlinemetered.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_addlinemetered::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/canvas/addlinemetered/cpp/fidl.h>
#include <examples/fidl/new/canvas/add_line_metered/hlcpp/client/config.h>
#include "lib/fpromise/result.h"
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples::canvas::addlinemetered::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples::canvas::addlinemetered::Point{.x = x, .y = y};
}
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
::std::array<::examples::canvas::addlinemetered::Point, 2> ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace, then create an asynchronous client
// using the newly-established connection.
examples::canvas::addlinemetered::InstancePtr instance_proxy;
auto context = sys::ComponentContext::Create();
context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
FX_LOGS(INFO) << "Outgoing connection enabled";
instance_proxy.set_error_handler([&loop](zx_status_t status) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
loop.Quit();
});
// Provide a lambda to handle incoming |OnDrawn| events asynchronously.
instance_proxy.events().OnDrawn = [&loop](
::examples::canvas::addlinemetered::Point top_left,
::examples::canvas::addlinemetered::Point bottom_right) {
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop.Quit();
};
instance_proxy.events().handle_unknown_event = [](uint64_t ordinal) {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << ordinal;
};
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
auto line = ParseLine(action);
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
instance_proxy->AddLine(line, [&](fpromise::result<void, fidl::FrameworkErr> result) {
if (result.is_error()) {
// Check that our flexible two-way call was known to the server and handle the case of an
// unknown method appropriately. In the case of this example, there is nothing we can do to
// recover here, except to log an error and exit the program.
FX_LOGS(ERROR) << "Server does not implement AddLine";
}
FX_LOGS(INFO) << "AddLine response received";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>
#include <lib/async/cpp/task.h>
#include <lib/fidl/cpp/binding.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/canvas/addlinemetered/cpp/fidl.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples::canvas::addlinemetered::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::addlinemetered::Instance {
public:
// Bind this implementation to an |InterfaceRequest|.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::InterfaceRequest<examples::canvas::addlinemetered::Instance> request)
: binding_(fidl::Binding<examples::canvas::addlinemetered::Instance>(this)),
weak_factory_(this) {
binding_.Bind(std::move(request), dispatcher);
// Gracefully handle abrupt shutdowns.
binding_.set_error_handler([this](zx_status_t status) mutable {
if (status != ZX_ERR_PEER_CLOSED) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
});
// Start the update timer on startup. Our server sends one update per second.
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLine(::std::array<::examples::canvas::addlinemetered::Point, 2> line,
AddLineCallback callback) override {
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : line) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
// Because this is now a two-way method, we must use the generated |callback| to send an in
// this case empty reply back to the client. This is the mechanic which syncs the flow rate
// between the client and server on this method, thereby preventing the client from "flooding"
// the server with unacknowledged work.
callback(fpromise::ok());
FX_LOGS(INFO) << "AddLine response sent";
}
void handle_unknown_method(uint64_t ordinal, bool method_has_response) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = state_.bounding_box.top_left;
auto bottom_right = state_.bounding_box.bottom_right;
binding_.events().OnDrawn(top_left, bottom_right);
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change tracker.
state_.changed = false;
},
after);
}
fidl::Binding<examples::canvas::addlinemetered::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
//
// Note that unlike the new C++ bindings, HLCPP bindings rely on the async loop being attached to
// the current thread via the |kAsyncLoopConfigAttachToCurrentThread| configuration.
async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component.
// This directory is where the outgoing FIDL protocols are installed so that they can be
// provided to other components.
auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
// Register a handler for components trying to connect to
// |examples.canvas.addlinemetered.Instance|.
context->outgoing()->AddPublicService(
fidl::InterfaceRequestHandler<examples::canvas::addlinemetered::Instance>(
[dispatcher](fidl::InterfaceRequest<examples::canvas::addlinemetered::Instance> request) {
// Create an instance of our |InstanceImpl| that destroys itself when the connection
// closes.
new InstanceImpl(dispatcher, std::move(request));
}));
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
别名
FIDL 配方：别名
alias 是为现有类型分配新名称的 FIDL 声明。这样做有几个好处：
- 使用
alias可确保别名类型所代表的概念具有单一可信来源。 - 它提供了一种命名对象（尤其是受限类型）的方式。
- 现在别名类型的不同用途可以被链接为同一概念的实例。
请务必注意，别名目前不会传递到生成的绑定代码。也就是说，分配给 alias 声明的名称绝不会在生成的 FIDL 代码中显示为声明名称。
在此示例中，为 Key 添加 alias 可以避免定制名称重复，同时还向读取者明确说明 Item 类型上的 key 值和 ReadItem 请求结构体中使用的 key 是同一内容，并非恰好是偶然。
推理
原来的只写键值对存储区现已扩展，能够从存储区中读回项。
实现
对 FIDL 和 CML 定义的更改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.addreaditem;
// Aliases for the key and value. Using aliases helps increase the readability of FIDL files and
// reduces likelihood of errors due to differing constraints.
alias Key = string:128;
alias Value = vector<byte>:64000;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key Key;
value Value;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to read a value out of our store.
type ReadError = flexible enum {
UNKNOWN = 0;
NOT_FOUND = 1;
};
/// A very basic key-value store - so basic, in fact, that one may only write to it, never read!
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Reads an item from the store.
flexible ReadItem(struct {
key Key;
}) -> (Item) error ReadError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.addreaditem.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
read_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.addreaditem.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.addreaditem.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.addreaditem.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
所有语言的客户端和服务器实现也会发生变化：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_addreaditem::{Item, StoreMarker},
fuchsia_component::client::connect_to_protocol,
std::{str, thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// The structured config for this client contains `read_items`, a vector of strings, each of
// which is meant to be read from the key-value store. We iterate over these keys, attempting to
// read them in turn.
for key in config.read_items.into_iter() {
let res = store.read_item(key.as_str()).await;
match res.unwrap() {
Ok(val) => {
println!("ReadItem Success: key: {}, value: {}", key, str::from_utf8(&val.1)?)
}
Err(err) => println!("ReadItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_addreaditem::{
Item, ReadError, StoreRequest, StoreRequestStream, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z][A-Za-z0-9_\./]{2,62}[A-Za-z0-9]$")
.expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut HashMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Vec<u8>>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::ReadItem { key, responder } => {
println!("ReadItem request received");
// Read the item from the store, returning the appropriate error if it could not be found.
responder
.send(match store.borrow().get(&key) {
Some(found) => {
println!("Read value at key: {}", key);
Ok((&key, found))
}
None => {
println!("Read error: NOT_FOUND, For key: {}", key);
Err(ReadError::NotFound)
}
})
.context("error sending reply")?;
println!("ReadItem response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
匿名类型
FIDL 配方：匿名类型
匿名类型是一种类型，其定义内嵌于其用途中，而不是位于独立的已命名 type 声明中。使用匿名类型有两点好处。首先，它们可防止过度的命名空间污染，从而解决了 FIDL 作者需要对仅使用一次的类型命名的需求。其次，它们会阻止通过 using 声明将该类型导入另一个 FIDL 库，因为无法通过名称识别类型。
在此变体中，我们允许键值对存储区将其他键值对存储区作为成员。简而言之，我们将其变成一棵树。为此，我们将 value 的原始定义替换为使用双成员 union 的定义：一个变体使用与之前相同的 vector<byte> 类型存储叶节点，而另一个变体以其他嵌套存储的形式存储分支节点。
推理
在这里，我们看到可选性的几种用途，我们可以借此声明一个可能存在或可能不存在的类型。FIDL 中有三种可选类型：
- 始终在线在线存储的类型，因此有一种内置方式，通过 null 信封来描述“缺失”。为这些类型启用可选性不会影响包含它们的消息的传输形状，而只是更改该特定类型有效的值。通过添加
:optional约束条件，union、vector<T>、client_end、server_end和zx.Handle类型均可设为可选类型。通过将valueunion设为可选，我们能够采用不存在的value的形式引入规范的“null”条目。这意味着空bytes和缺失/空store属性都是无效值。 - 与上述类型不同，
struct布局没有额外的空间可存储 null 标头。因此，需要将其封装在信封中，从而更改包含它的消息的线上形状。为了确保这种导线修改效果易于辨认，必须将Itemstruct类型封装在box<T>类型模板中。 - 最后，
table布局始终是可选的。如果table不存在，则只是未设置任何成员的标识符。
树是一种天生的自引用数据结构：树中的任何节点都可能包含具有纯数据的叶（在本例中为字符串）或具有更多节点的子树。这需要递归：Item 的定义现在以传递方式依赖于其本身！在 FIDL 中表示递归类型可能有点复杂，尤其是因为目前对支持的内容有些有限。只要自引用创建的周期中至少有一个可选类型，我们就可以支持此类类型。例如，在这里，我们将 items struct 成员定义为 box<Item>，从而打破包含循环。
这些更改还大量使用了匿名类型（即声明内嵌在其单一使用点的类型），而不是被命名的顶级 type 声明。默认情况下，生成的语言绑定中的匿名类型名称取自其本地上下文。例如，新引入的 flexible union 将采用其自有成员的名称 Value，新引入的 struct 将变为 Store，依此类推。由于这种启发式方法有时可能会导致冲突，因此 FIDL 提供了应急方法，允许作者手动替换匿名类型的生成名称。这是通过 @generated_name 属性实现的，该属性可用于更改后端生成的名称。我们可以在这里使用一个示例，将原本的 Store 类型重命名为 NestedStore，以防止名称与使用相同名称的 protocol 声明发生名称冲突。
实现
FIDL、CML 和 Realm 接口定义修改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supporttrees;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value strict union {
// Keep the original `bytes` as one of the options in the new union. All leaf nodes in the
// tree must be `bytes`, or absent unions (representing empty). Empty byte arrays are
// disallowed.
1: bytes vector<byte>:64000;
// Allows a store within a store, thereby turning our flat key-value store into a tree
// thereof. Note the use of `@generated_name` to prevent a type-name collision with the
// `Store` protocol below, and the use of `box<T>` to ensure that there is a break in the
// chain of recursion, thereby allowing `Item` to include itself in its own definition.
//
// This is a table so that added fields, like for example a `hash`, can be easily added in
// the future.
2: store @generated_name("nested_store") table {
1: items vector<box<Item>>;
};
}:optional;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A newline separated list nested entries. The first line should be the key
// for the nested store, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
write_nested: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A list of keys, all of which will be populated as null entries.
write_null: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_supporttrees::{Item, NestedStore, StoreMarker, Value},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
let res = store
.write_item(&Item {
key: key.clone(),
value: Some(Box::new(Value::Bytes(value.into_bytes()))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Add nested entries to the key-value store as well. The entries are strings, where the first
// line is the key of the entry, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
for spec in config.write_nested.into_iter() {
let mut items = vec![];
let mut nested_store = NestedStore::default();
let mut lines = spec.split("\n");
let key = lines.next().unwrap();
// For each entry, make a new entry in the `NestedStore` being built.
for entry in lines {
let path = format!("/pkg/data/{}.txt", entry);
let contents = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
items.push(Some(Box::new(Item {
key: entry.to_string(),
value: Some(Box::new(Value::Bytes(contents.into()))),
})));
}
nested_store.items = Some(items);
// Send the `NestedStore`, represented as a vector of values.
let res = store
.write_item(&Item {
key: key.to_string(),
value: Some(Box::new(Value::Store(nested_store))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Each entry in this list is a null value in the store.
for key in config.write_null.into_iter() {
match store.write_item(&Item { key: key.to_string(), value: None }).await? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_supporttrees::{
Item, StoreRequest, StoreRequestStream, Value, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
std::str::from_utf8,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
// A representation of a key-value store that can contain an arbitrarily deep nesting of other
// key-value stores.
#[allow(dead_code)] // TODO(https://fxbug.dev/318827209)
enum StoreNode {
Leaf(Option<Vec<u8>>),
Branch(Box<HashMap<String, StoreNode>>),
}
/// Recursive item writer, which takes a `StoreNode` that may not necessarily be the root node, and
/// writes an entry to it.
fn write_item(
store: &mut HashMap<String, StoreNode>,
attempt: Item,
path: &str,
) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
let key = format!("{}{}", &path, entry.key());
match attempt.value {
// Null entries are allowed.
None => {
println!("Wrote value: NONE at key: {}", key);
entry.insert(StoreNode::Leaf(None));
}
Some(value) => match *value {
// If this is a nested store, recursively make a new store to insert at this
// position.
Value::Store(entry_list) => {
// Validate the value - absent stores, items lists with no children, or any
// of the elements within that list being empty boxes, are all not allowed.
if entry_list.items.is_some() {
let items = entry_list.items.unwrap();
if !items.is_empty() && items.iter().all(|i| i.is_some()) {
let nested_path = format!("{}/", key);
let mut nested_store = HashMap::<String, StoreNode>::new();
for item in items.into_iter() {
write_item(&mut nested_store, *item.unwrap(), &nested_path)?;
}
println!("Created branch at key: {}", key);
entry.insert(StoreNode::Branch(Box::new(nested_store)));
return Ok(());
}
}
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
// This is a simple leaf node on this branch.
Value::Bytes(value) => {
// Validate the value.
if value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
println!("Wrote key: {}, value: {:?}", key, from_utf8(&value).unwrap());
entry.insert(StoreNode::Leaf(Some(value)));
}
},
}
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, StoreNode>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt, ""))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
块数
FIDL 配方：位
bits 类型是 FIDL 表示位数组的方式。在需要一组布尔值标志的情况下使用。bits 数组通常用于“在”底层子类型的“上方”，该子类型控制其在线路上的位宽。
推理
键值对存储基准示例的实现是一个很好的起点，但一个主要缺点是数据存储为原始字节。FIDL 是一种类型丰富的语言。例如，强制将 UTF-8 字符串存储为非类型字节数组的数据，对于 *.fidl 文件的读取器以及使用从该文件生成的绑定的编程人员来说，都会清除这些有价值的类型信息。
实现
这项更改的主要目标是将基准用例的 vector<byte> 类型 value 成员替换为用于存储许多可能类型的 union。事实上，经过此次变更，您可以很好地了解 FIDL 的值类型：
- FIDL 的所有内置标量类型在
Valueunion中用作变体：bool、uint8、uint16、uint32、uint64、int8、int16、int32、int64、float32和float64（也称为 FIDL 的基元类型）以及string。 - 此
union还包含使用 FIDL 的内置array<T, N>和vector<T>类型模板的功能。 - 此示例中使用 FIDL 的所有类型布局（即
bits、enum、table、union和struct）至少一次。
用于 WriteItem 的请求和响应载荷也已分别从 struct 更改为命名的 table 和内嵌的 flexible union。事实上，这三种布局中的任何一种均可用作请求/响应负载。后两者（分别称为表载荷和 *联合载荷）在除消息大小对最敏感的用例之外，是首选。这是因为将来以与二进制文件兼容的方式扩展这些变量会更容易。
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.usegenericvalues;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value Value;
};
// Because the `Value` must be used both in the request and the response, we give it its own named
// type. The type is a `union` of all possible data types that we take as values, and is marked
// `flexible` to allow for the easy addition of new data types in the future.
type Value = flexible union {
// Keep the original `bytes` as one of the options in the new union.
1: bytes vector<byte>:64000;
// A `string` is very similar to `vector<byte>` on the wire, with the extra constraint that
// it enforces that it enforces that the byte vector in question is valid UTF-8.
2: string string:64000;
// All of FIDL's primitive types.
3: bool bool;
4: uint8 uint8;
5: int8 int8;
6: uint16 uint16;
7: int16 int16;
8: uint32 uint32;
9: int32 int32;
10: float32 float32;
11: uint64 uint64;
12: int64 int64;
13: float64 float64;
// FIDL does not natively support 128-bit integer types, so we have to define our own
// representations.
14: uint128 array<uint64, 2>;
};
// Because we now supoprt a richer range of types as values in our store, it is helpful to use a
// `flexible`, and therefore evolvable, `bits` type to store write options.
type WriteOptions = flexible bits : uint8 {
// This flag allows us to overwrite existing data when there is a collision, rather than failing
// with an `WriteError.ALREADY_EXISTS`.
OVERWRITE = 0b1;
// This flag allows us to concatenate to existing data when there is a collision, rather than
// failing with an `WriteError.ALREADY_EXISTS`. "Concatenation" means addition for the numeric
// variants and appending to the `bytes`/`string` variants. If no existing data can be found, we
// "concatenate" to default values of zero and an empty vector, respectively. Attempting to
// concatenate to an existing variant of a different type will return a
// `WriteError.INVALID_VALUE` error.
CONCAT = 0b10;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
///
/// Since the value stored in the key-value store can now be different from the input (if the
/// `WriteOptions.CONCAT` flag is set), we need to return the resulting `Value` to the
/// requester.
///
/// We use an (anonymous) `table` and a (named) `flexible union` as the request and response
/// payload, respectively, to allow for easier future evolution. Both of these types are
/// `flexible`, meaning that adding or removing members is binary-compatible. This makes them
/// much easier to evolve that the `struct` types that were previously used, which cannot be
/// changed after release without breaking ABI.
flexible WriteItem(table {
1: attempt Item;
2: options WriteOptions;
}) -> (Value) error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
config: {
// A vector of values for every easily representible type in our key-value store. For
// brevity's sake, the 8, 16, and 32 bit integer types and booleans are omitted.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use all FIDL constructs directly here. In
// particular, floats and nested types are very difficult to represent, and have been
// excluded from this example for the time being.
set_concat_option: { type: "bool" },
set_overwrite_option: { type: "bool" },
write_bytes: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_strings: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_uint64s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
write_int64s: {
type: "vector",
max_count: 16,
element: { type: "int64" },
},
// Note: due to the limitation of structured config not allowing vectors nested in vectors,
// we only set the lower half of the uint128 for simplicity's sake.
write_uint128s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreMarker, StoreProxy, StoreWriteItemRequest, Value, WriteOptions,
},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
// A helper function to sequentially write a single item to the key-value store and print a log when
// successful.
async fn write_next_item(
store: &StoreProxy,
key: &str,
value: Value,
options: WriteOptions,
) -> Result<(), Error> {
// Create an empty request payload using `::default()`.
let mut req = StoreWriteItemRequest::default();
req.options = Some(options);
// Fill in the `Item` we will be attempting to write.
println!("WriteItem request sent: key: {}, value: {:?}", &key, &value);
req.attempt = Some(Item { key: key.to_string(), value: value });
// Send and async `WriteItem` request to the server.
match store.write_item(&req).await.context("Error sending request")? {
Ok(value) => println!("WriteItem response received: {:?}", &value),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
Ok(())
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// All of our requests will have the same bitflags set. Pull these settings from the config.
let mut options = WriteOptions::empty();
options.set(WriteOptions::OVERWRITE, config.set_overwrite_option);
options.set(WriteOptions::CONCAT, config.set_concat_option);
// The structured config provides one input for most data types that can be stored in the data
// store. Iterate through those inputs in the order we see them in the FIDL file.
//
// Note that FIDL unions are rendered as enums in Rust; for example, the `Value` union has now
// become a `Value` Rust enum, with each member taking exactly one argument.
for value in config.write_bytes.into_iter() {
write_next_item(&store, "bytes", Value::Bytes(value.into()), options).await?;
}
for value in config.write_strings.into_iter() {
write_next_item(&store, "string", Value::String(value), options).await?;
}
for value in config.write_uint64s.into_iter() {
write_next_item(&store, "uint64", Value::Uint64(value), options).await?;
}
for value in config.write_int64s.into_iter() {
write_next_item(&store, "int64", Value::Int64(value), options).await?;
}
for value in config.write_uint128s.into_iter() {
write_next_item(&store, "uint128", Value::Uint128([0, value]), options).await?;
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
use {
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreRequest, StoreRequestStream, Value, WriteError, WriteOptions,
},
std::collections::hash_map::OccupiedEntry,
std::ops::Add,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Sums any numeric type.
fn sum<T: Add + Add<Output = T> + Copy>(operands: [T; 2]) -> T {
operands[0] + operands[1]
}
/// Clones and inserts an entry, so that the original (now concatenated) copy may be returned in the
/// response.
fn write(inserting: Value, mut entry: OccupiedEntry<'_, String, Value>) -> Value {
entry.insert(inserting.clone());
println!("Wrote key: {}, value: {:?}", entry.key(), &inserting);
inserting
}
/// Handler for the `WriteItem` method.
fn write_item(
store: &mut HashMap<String, Value>,
attempt: Item,
options: &WriteOptions,
) -> Result<Value, WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY for key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
// The `CONCAT` flag supersedes the `OVERWRITE` flag, so check it first.
if options.contains(WriteOptions::CONCAT) {
match entry.get() {
Value::Bytes(old) => {
if let Value::Bytes(new) = attempt.value {
let mut combined = old.clone();
combined.extend(new);
return Ok(write(Value::Bytes(combined), entry));
}
}
Value::String(old) => {
if let Value::String(new) = attempt.value {
return Ok(write(Value::String(format!("{}{}", old, &new)), entry));
}
}
Value::Uint64(old) => {
if let Value::Uint64(new) = attempt.value {
return Ok(write(Value::Uint64(sum([*old, new])), entry));
}
}
Value::Int64(old) => {
if let Value::Int64(new) = attempt.value {
return Ok(write(Value::Int64(sum([*old, new])), entry));
}
}
// Note: only works on the uint64 range in practice.
Value::Uint128(old) => {
if let Value::Uint128(new) = attempt.value {
return Ok(write(Value::Uint128([0, sum([old[1], new[1]])]), entry));
}
}
_ => {
panic!("actively unsupported type!")
}
}
// Only reachable if the type of the would be concatenated value did not match the
// value already occupying this entry.
println!("Write error: INVALID_VALUE for key: {}", entry.key());
return Err(WriteError::InvalidValue);
}
// If we're not doing CONCAT, check for OVERWRITE next.
if options.contains(WriteOptions::OVERWRITE) {
return Ok(write(attempt.value, entry));
}
println!("Write error: ALREADY_EXISTS for key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote key: {}, value: {:?}", entry.key(), &attempt.value);
entry.insert(attempt.value.clone());
Ok(attempt.value)
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Value>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
// Because we are using a table payload, there is an extra level of indirection. The
// top-level container for the table itself is always called "payload".
StoreRequest::WriteItem { payload, responder } => {
println!("WriteItem request received");
// Error out if either of the request table's members are not set.
let attempt = payload.attempt.context("required field 'attempt' is unset")?;
let options = payload.options.context("required field 'options' is unset")?;
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(
write_item(&mut store.borrow_mut(), attempt, &options)
.as_ref()
.map_err(|e| *e),
)
.context("error sending reply")?;
println!("WriteItem response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
可检测到
FIDL 配方：@discoverable
@discoverable 属性为服务发现分配名称。这样，客户端就可以搜索正确的名称，而无需手动确保查询名称与服务器端传递的名称一致。
在此示例中，您将创建一个基本的计算器服务器和客户端，该服务器和客户端显示了首先定义然后传送和使用 FIDL 协议所需的基本设置。
首先，您需要定义接口定义和自动化测试框架。接口定义（.fidl 文件本身）是所有新 FIDL 协议的起点。此外，该计算器包含创建客户端-服务器模式所需的 CML 和领域定义，这些模式可用作任意实现的项目基架。
FIDL 代码如下所示：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// The namespace for this FIDL protocol. This namespace is how both consumers (clients) and providers (servers) reference this protocol.
library examples.calculator.baseline;
// @discoverable indicates 'Calculator' is a protocol that will be served under the examples.calculator.baseline libarary namespace. https://fuchsia.dev/fuchsia-src/reference/fidl/language/attributes#discoverable . If @discoverable is missing, it will lead to a compile time error when trying to import the library.
@discoverable
// A limited-functionality calculator 'protocol' that adds and subtracts integers.
open protocol Calculator {
// Takes as input a struct with two integers, and returns their sum: (a+b)=sum. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Add(struct {
a int32;
b int32;
}) -> (struct {
sum int64;
});
// Takes as input a struct with two integers, and returns their difference: (a-b)=difference. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Subtract(struct {
a int32;
b int32;
}) -> (struct {
difference int64;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
config: {},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
expose: [
{
protocol: "examples.calculator.baseline.Calculator",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.calculator.baseline.Calculator",
from: "#server",
to: "#client",
},
// Route logging support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// TODO(https://fxbug.dev/42063075): Rust implementation.
服务器
// TODO(https://fxbug.dev/42063075): Rust implementation.
C++（自然）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
对于某些开发者（例如平台开发者）来说，从头开始创建 FIDL 协议（如此示例所示）可能是更常见的场景。不过，其他类型的开发者也可以受益于学习如何构造 FIDL 协议（即使他们通常不会这样做）。这有助于您了解 FIDL 的所有要素，包括语法、语法、语言功能、如何提供和使用给定 FIDL 协议，以及构建系统的工作原理。对于后续步骤，此基准后面的示例展示了如何扩展现有的 FIDL 协议，这应该是一种相当常见的做法。
枚举
FIDL 配方：枚举
枚举是一种 FIDL 数据类型，表示可能常量的固定列表，如纸牌中的套装或用户可以从下拉菜单中选择的汽车品牌。然后，该值列表会映射到基础整数类型，其中每个值都对应于列出的其中一个成员。
在下面的示例中，在适合使用枚举的情况下添加了 FIDL 枚举：枚举方法调用失败时可能发出的错误值。ReadError 枚举具有两个成员：NOT_FOUND 用于指示在读取尝试期间无法匹配搜索键值，而 UNKNOWN 在所有无法明确描述的情况下用作抓取袋错误。请注意，此枚举被标记为 flexible，未来可以轻松地随新成员一起改进。
推理
原来的只写键值对存储区现已扩展，能够从存储区中读回项。
实现
对 FIDL 和 CML 定义的更改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.addreaditem;
// Aliases for the key and value. Using aliases helps increase the readability of FIDL files and
// reduces likelihood of errors due to differing constraints.
alias Key = string:128;
alias Value = vector<byte>:64000;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key Key;
value Value;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to read a value out of our store.
type ReadError = flexible enum {
UNKNOWN = 0;
NOT_FOUND = 1;
};
/// A very basic key-value store - so basic, in fact, that one may only write to it, never read!
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Reads an item from the store.
flexible ReadItem(struct {
key Key;
}) -> (Item) error ReadError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.addreaditem.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
read_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.addreaditem.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.addreaditem.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.addreaditem.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
所有语言的客户端和服务器实现也会发生变化：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_addreaditem::{Item, StoreMarker},
fuchsia_component::client::connect_to_protocol,
std::{str, thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// The structured config for this client contains `read_items`, a vector of strings, each of
// which is meant to be read from the key-value store. We iterate over these keys, attempting to
// read them in turn.
for key in config.read_items.into_iter() {
let res = store.read_item(key.as_str()).await;
match res.unwrap() {
Ok(val) => {
println!("ReadItem Success: key: {}, value: {}", key, str::from_utf8(&val.1)?)
}
Err(err) => println!("ReadItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_addreaditem::{
Item, ReadError, StoreRequest, StoreRequestStream, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z][A-Za-z0-9_\./]{2,62}[A-Za-z0-9]$")
.expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut HashMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Vec<u8>>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::ReadItem { key, responder } => {
println!("ReadItem request received");
// Read the item from the store, returning the appropriate error if it could not be found.
responder
.send(match store.borrow().get(&key) {
Some(found) => {
println!("Read value at key: {}", key);
Ok((&key, found))
}
None => {
println!("Read error: NOT_FOUND, For key: {}", key);
Err(ReadError::NotFound)
}
})
.context("error sending reply")?;
println!("ReadItem response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
前馈模式
FIDL 配方：前馈模式
在 FIDL 协议中，出于流控制目的使用具有空响应的双向方法（例如 DoSomething(...) -> ();）存在一个对延迟敏感协议的基本缺陷：调用方要么等待每个回复，然后再发送下一条消息，从而增加每条消息的延迟时间；要么它们会忽略这条消息，使空回复本身变得毫无意义。如果协议需要流控制而不会导致此类延迟出现，则不错的替代方案是前馈模式。在此设置中，一种或多种单向方法向服务器写入数据，而其他方法（单向或双向）用于“提交”工作并在客户端和服务器之间同步。这意味着可以尽可能快地传输任意数量的数据，但仍存在一定程度的流控制，因为同步方法会强制客户端停止，然后继续执行更多工作。
提升 Instance 协议性能的一种方法是允许批量调用行：我们可以将多行批量调用为一次新的 AddLines(...); 调用，而不是每次要在画布中添加新行时都发送一个 AddLine(...);，等待回复，然后再针对下一行执行此操作。客户端现在可以决定如何以最佳方式对要绘制的大型线条集合进行划分。
如果只是单纯地实现，我们会发现服务器和客户端完全不同步：客户端可以使用无界限的 AddLines(...); 调用对服务器进行泛洪处理，而服务器同样可能向客户端填充超出其处理能力的 -> OnDrawn(...); 事件。这两个问题的解决方案就是添加一个简单的 Ready() -> (); 方法以进行同步。每当客户端准备好接收下一次绘图更新时，都会调用此方法，并且来自服务器的响应表明客户端可以继续处理更多请求。
现在，我们在两个方向上都进行了一些流控制。该协议现在实现了前馈模式，允许在某个同步的“提交”调用触发服务器上的实际工作之前进行许多不受控制的调用。这可以防止客户端处理大量工作，导致服务器不堪重负。同样，不再允许服务器发送无界限 -> OnDrawn(...); 事件：每个事件都必须遵循来自客户端的一个信号，即 Ready() -> (); 调用，这表示它已准备好执行更多工作。这称为节流事件模式。
具体实现必须手动应用其中某些规则：如果客户端收到其未通过 Ready() -> (); 方法请求的 -> OnDrawn(...); 事件，则必须关闭连接。
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.canvas.clientrequesteddraw;
/// A point in 2D space.
type Point = struct {
x int64;
y int64;
};
/// A line in 2D space.
alias Line = array<Point, 2>;
/// A bounding box in 2D space. This is the result of "drawing" operations on our canvas, and what
/// the server reports back to the client. These bounds are sufficient to contain all of the
/// lines (inclusive) on a canvas at a given time.
type BoundingBox = struct {
top_left Point;
bottom_right Point;
};
/// Manages a single instance of a canvas. Each session of this protocol is responsible for a new
/// canvas.
@discoverable
open protocol Instance {
/// Add multiple lines to the canvas. We are able to reduce protocol chatter and the number of
/// requests needed by batching instead of calling the simpler `AddLine(...)` one line at a
/// time.
flexible AddLines(struct {
lines vector<Line>;
});
/// Rather than the server randomly performing draws, or trying to guess when to do so, the
/// client must explicitly ask for them. This creates a bit of extra chatter with the additional
/// method invocation, but allows much greater client-side control of when the canvas is "ready"
/// for a view update, thereby eliminating unnecessary draws.
///
/// This method also has the benefit of "throttling" the `-> OnDrawn(...)` event - rather than
/// allowing a potentially unlimited flood of `-> OnDrawn(...)` calls, we now have the runtime
/// enforced semantic that each `-> OnDrawn(...)` call must follow a unique `Ready() -> ()` call
/// from the client. An unprompted `-> OnDrawn(...)` is invalid, and should cause the channel to
/// immediately close.
flexible Ready() -> ();
/// Update the client with the latest drawing state. The server makes no guarantees about how
/// often this event occurs - it could occur multiple times per board state, for example.
flexible -> OnDrawn(BoundingBox);
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.canvas.clientrequesteddraw.Instance" },
],
config: {
// A script for the client to follow. Entries in the script may take one of two forms: a
// pair of signed-integer coordinates like "-2,15:4,5", or the string "READY". The former
// builds a local vector sent via a single `AddLines(...)` call, while the latter sends a
// `Ready() -> ()` call pauses execution until the next `->OnDrawn(...)` event is received.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use a vector of `union { Point; Ready}` here.
script: {
type: "vector",
max_count: 100,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.canvas.clientrequesteddraw.Instance" },
],
expose: [
{
protocol: "examples.canvas.clientrequesteddraw.Instance",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.canvas.clientrequesteddraw.Instance",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{format_err, Context as _, Error},
config::Config,
fidl_examples_canvas_clientrequesteddraw::{InstanceEvent, InstanceMarker, Point},
fuchsia_component::client::connect_to_protocol,
futures::TryStreamExt,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send Instance requests
// across the channel.
let instance = connect_to_protocol::<InstanceMarker>()?;
println!("Outgoing connection enabled");
let mut batched_lines = Vec::<[Point; 2]>::new();
for action in config.script.into_iter() {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if action == "PUSH" {
instance.add_lines(&batched_lines).context("Could not send lines")?;
println!("AddLines request sent");
batched_lines.clear();
continue;
}
// If the next action in the script is to "WAIT", block until an OnDrawn event is received
// from the server.
if action == "WAIT" {
let mut event_stream = instance.take_event_stream();
loop {
match event_stream
.try_next()
.await
.context("Error getting event response from proxy")?
.ok_or_else(|| format_err!("Proxy sent no events"))?
{
InstanceEvent::OnDrawn { top_left, bottom_right } => {
println!(
"OnDrawn event received: top_left: {:?}, bottom_right: {:?}",
top_left, bottom_right
);
break;
}
InstanceEvent::_UnknownEvent { ordinal, .. } => {
println!("Received an unknown event with ordinal {ordinal}");
}
}
}
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
println!("Ready request sent");
instance.ready().await.context("Could not send ready call")?;
println!("Ready success");
continue;
}
// Add a line to the next batch. Parse the string input, making two points out of it.
let mut points = action
.split(":")
.map(|point| {
let integers = point
.split(",")
.map(|integer| integer.parse::<i64>().unwrap())
.collect::<Vec<i64>>();
Point { x: integers[0], y: integers[1] }
})
.collect::<Vec<Point>>();
// Assemble a line from the two points.
let from = points.pop().ok_or(format_err!("line requires 2 points, but has 0"))?;
let to = points.pop().ok_or(format_err!("line requires 2 points, but has 1"))?;
let mut line: [Point; 2] = [from, to];
// Batch a line for drawing to the canvas using the two points provided.
println!("AddLines batching line: {:?}", &mut line);
batched_lines.push(line);
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{anyhow, Context as _, Error},
fidl::endpoints::RequestStream as _,
fidl_examples_canvas_clientrequesteddraw::{
BoundingBox, InstanceRequest, InstanceRequestStream, Point,
},
fuchsia_async::{Time, Timer},
fuchsia_component::server::ServiceFs,
fuchsia_zircon::{self as zx},
futures::future::join,
futures::prelude::*,
std::sync::{Arc, Mutex},
};
// A struct that stores the two things we care about for this example: the bounding box the lines
// that have been added thus far, and bit to track whether or not there have been changes since the
// last `OnDrawn` event.
#[derive(Debug)]
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
changed: bool,
// Tracks whether or not the client has declared itself ready to receive more updated.
ready: bool,
bounding_box: BoundingBox,
}
/// Handler for the `AddLines` method.
fn add_lines(state: &mut CanvasState, lines: Vec<[Point; 2]>) {
// Update the bounding box to account for the new lines we've just "added" to the canvas.
let bounds = &mut state.bounding_box;
for line in lines {
println!("AddLines printing line: {:?}", line);
for point in line {
if point.x < bounds.top_left.x {
bounds.top_left.x = point.x;
}
if point.y > bounds.top_left.y {
bounds.top_left.y = point.y;
}
if point.x > bounds.bottom_right.x {
bounds.bottom_right.x = point.x;
}
if point.y < bounds.bottom_right.y {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next tick.
state.changed = true
}
/// Creates a new instance of the server, paired to a single client across a zircon channel.
async fn run_server(stream: InstanceRequestStream) -> Result<(), Error> {
// Create a new in-memory state store for the state of the canvas. The store will live for the
// lifetime of the connection between the server and this particular client.
let state = Arc::new(Mutex::new(CanvasState {
changed: true,
ready: true,
bounding_box: BoundingBox {
top_left: Point { x: 0, y: 0 },
bottom_right: Point { x: 0, y: 0 },
},
}));
// Take ownership of the control_handle from the stream, which will allow us to push events from
// a different async task.
let control_handle = stream.control_handle();
// A separate watcher task periodically "draws" the canvas, and notifies the client of the new
// state. We'll need a cloned reference to the canvas state to be accessible from the new
// task.
let state_ref = state.clone();
let update_sender = || async move {
loop {
// Our server sends one update per second, but only if the client has declared that it
// is ready to receive one.
Timer::new(Time::after(zx::Duration::from_seconds(1))).await;
let mut state = state_ref.lock().unwrap();
if !state.changed || !state.ready {
continue;
}
// After acquiring the lock, this is where we would draw the actual lines. Since this is
// just an example, we'll avoid doing the actual rendering, and simply send the bounding
// box to the client instead.
let bounds = state.bounding_box;
match control_handle.send_on_drawn(&bounds.top_left, &bounds.bottom_right) {
Ok(_) => println!(
"OnDrawn event sent: top_left: {:?}, bottom_right: {:?}",
bounds.top_left, bounds.bottom_right
),
Err(_) => return,
}
// Reset the change and ready trackers.
state.ready = false;
state.changed = false;
}
};
// Handle requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
let state_ref = &state;
let request_handler =
stream.map(|result| result.context("failed request")).try_for_each(|request| async move {
// Match based on the method being invoked.
match request {
InstanceRequest::AddLines { lines, .. } => {
println!("AddLines request received");
add_lines(&mut state_ref.lock().unwrap(), lines);
}
InstanceRequest::Ready { responder, .. } => {
println!("Ready request received");
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();`
// event; if two "consecutive" `Ready() -> ();` calls are received, this
// interaction has entered an invalid state, and should be aborted immediately.
let mut state = state_ref.lock().unwrap();
if state.ready == true {
return Err(anyhow!("Invalid back-to-back `Ready` requests received"));
}
state.ready = true;
responder.send().context("Error responding")?;
} //
InstanceRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
});
// This line will only be reached if the server errors out. The stream will await indefinitely,
// thereby creating a long-lived server. Here, we first wait for the updater task to realize the
// connection has died, then bubble up the error.
join(request_handler, update_sender()).await.0
}
// A helper enum that allows us to treat a `Instance` service instance as a value.
enum IncomingService {
Instance(InstanceRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Instance` protocol - this will allow the client to see
// the server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Instance);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Instance(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/client_requested_draw/cpp_natural/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::AsyncEventHandler<examples_canvas_clientrequesteddraw::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(
fidl::Event<examples_canvas_clientrequesteddraw::Instance::OnDrawn>& event) override {
::examples_canvas_clientrequesteddraw::Point top_left = event.top_left();
::examples_canvas_clientrequesteddraw::Point bottom_right = event.bottom_right();
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y() << " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_clientrequesteddraw::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_clientrequesteddraw::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_clientrequesteddraw::Point(x, y);
}
using Line = ::std::array<::examples_canvas_clientrequesteddraw::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_clientrequesteddraw::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
fit::result<fidl::Error> result = client->AddLines(batched_lines);
if (!result.is_ok()) {
// Check that our one-way call was enqueued successfully, and handle the error
// appropriately. In the case of this example, there is nothing we can do to recover here,
// except to log an error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLines request: " << result.error_value();
return -1;
}
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
FX_LOGS(INFO) << "Ready request sent";
client->Ready().ThenExactlyOnce(
[&](fidl::Result<examples_canvas_clientrequesteddraw::Instance::Ready> result) {
// Check if the FIDL call succeeded or not.
if (result.is_ok()) {
FX_LOGS(INFO) << "Ready success";
} else {
FX_LOGS(ERROR) << "Could not send Ready request: " << result.error_value();
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x() << ", y: " << line[1].y()
<< " }, Point { x: " << line[0].x() << ", y: " << line[0].y() << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples_canvas_clientrequesteddraw::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_clientrequesteddraw::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLines(AddLinesRequest& request, AddLinesCompleter::Sync& completer) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : request.lines()) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x()
<< ", y: " << points[1].y() << " }, Point { x: " << points[0].x()
<< ", y: " << points[0].y() << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x() < bounds.top_left().x()) {
bounds.top_left().x() = point.x();
}
if (point.y() > bounds.top_left().y()) {
bounds.top_left().y() = point.y();
}
if (point.x() > bounds.bottom_right().x()) {
bounds.bottom_right().x() = point.x();
}
if (point.y() < bounds.bottom_right().y()) {
bounds.bottom_right().y() = point.y();
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void Ready(ReadyCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if two
// "consecutive" `Ready() -> ();` calls are received, this interaction has entered an invalid
// state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
completer.Reply();
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_clientrequesteddraw::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client has
// not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto result = fidl::SendEvent(binding_)->OnDrawn(state_.bounding_box);
if (!result.is_ok()) {
return;
}
auto top_left = state_.bounding_box.top_left();
auto bottom_right = state_.bounding_box.bottom_right();
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y()
<< " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
// Reset the change and ready trackers.
state_.ready = false;
state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_clientrequesteddraw::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++（有线）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/client_requested_draw/cpp_wire/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler
: public fidl::WireAsyncEventHandler<examples_canvas_clientrequesteddraw::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(
fidl::WireEvent<examples_canvas_clientrequesteddraw::Instance::OnDrawn>* event) override {
::examples_canvas_clientrequesteddraw::wire::Point top_left = event->top_left;
::examples_canvas_clientrequesteddraw::wire::Point bottom_right = event->bottom_right;
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_clientrequesteddraw::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_clientrequesteddraw::wire::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_clientrequesteddraw::wire::Point{.x = x, .y = y};
}
using Line = ::fidl::Array<::examples_canvas_clientrequesteddraw::wire::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_clientrequesteddraw::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
fidl::Status status = client->AddLines(fidl::VectorView<Line>::FromExternal(batched_lines));
if (!status.ok()) {
// Check that our one-way call was enqueued successfully, and handle the error
// appropriately. In the case of this example, there is nothing we can do to recover here,
// except to log an error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLines request: " << status.error();
return -1;
}
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
FX_LOGS(INFO) << "Ready request sent";
client->Ready().ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_canvas_clientrequesteddraw::Instance::Ready>&
result) {
// Check if the FIDL call succeeded or not.
if (result.ok()) {
FX_LOGS(INFO) << "Ready success";
} else {
FX_LOGS(ERROR) << "Could not send Ready request: " << result.error();
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples_canvas_clientrequesteddraw::wire::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_clientrequesteddraw::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLines(AddLinesRequestView request, AddLinesCompleter::Sync& completer) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : request->lines) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void Ready(ReadyCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if two
// "consecutive" `Ready() -> ();` calls are received, this interaction has entered an invalid
// state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
completer.Reply();
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_clientrequesteddraw::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client has
// not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = weak->state_.bounding_box.top_left;
auto bottom_right = weak->state_.bounding_box.bottom_right;
fidl::Status status =
fidl::WireSendEvent(weak->binding_)->OnDrawn(top_left, bottom_right);
if (!status.ok()) {
return;
}
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change and ready trackers.
state_.ready = false;
weak->state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_clientrequesteddraw::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/canvas/clientrequesteddraw/cpp/fidl.h>
#include <examples/fidl/new/canvas/client_requested_draw/hlcpp/client/config.h>
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples::canvas::clientrequesteddraw::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples::canvas::clientrequesteddraw::Point{.x = x, .y = y};
}
using Line = ::std::array<::examples::canvas::clientrequesteddraw::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace, then create an asynchronous client
// using the newly-established connection.
examples::canvas::clientrequesteddraw::InstancePtr instance_proxy;
auto context = sys::ComponentContext::Create();
context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
FX_LOGS(INFO) << "Outgoing connection enabled";
instance_proxy.set_error_handler([&loop](zx_status_t status) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
loop.Quit();
});
// Provide a lambda to handle incoming |OnDrawn| events asynchronously.
instance_proxy.events().OnDrawn =
[&loop](::examples::canvas::clientrequesteddraw::Point top_left,
::examples::canvas::clientrequesteddraw::Point bottom_right) {
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop.Quit();
};
instance_proxy.events().handle_unknown_event = [](uint64_t ordinal) {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << ordinal;
};
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
instance_proxy->AddLines(batched_lines);
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are ready
// for us.
FX_LOGS(INFO) << "Ready request sent";
instance_proxy->Ready([&](fpromise::result<void, fidl::FrameworkErr> result) {
if (result.is_error()) {
// Check that our flexible two-way call was known to the server and handle the case of an
// unknown method appropriately. In the case of this example, there is nothing we can do
// to recover here, except to log an error and exit the program.
FX_LOGS(ERROR) << "Server does not implement AddLine";
}
FX_LOGS(INFO) << "Ready success";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>
#include <lib/async/cpp/task.h>
#include <lib/fidl/cpp/binding.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/canvas/clientrequesteddraw/cpp/fidl.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples::canvas::clientrequesteddraw::BoundingBox bounding_box;
};
using Line = ::std::array<::examples::canvas::clientrequesteddraw::Point, 2>;
// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::clientrequesteddraw::Instance {
public:
// Bind this implementation to an |InterfaceRequest|.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::InterfaceRequest<examples::canvas::clientrequesteddraw::Instance> request)
: binding_(fidl::Binding<examples::canvas::clientrequesteddraw::Instance>(this)),
weak_factory_(this) {
binding_.Bind(std::move(request), dispatcher);
// Gracefully handle abrupt shutdowns.
binding_.set_error_handler([this](zx_status_t status) mutable {
if (status != ZX_ERR_PEER_CLOSED) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
});
// Start the update timer on startup. Our server sends one update per second.
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLines(std::vector<Line> lines) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : lines) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next
// |OnDrawn| event.
state_.changed = true;
}
void Ready(ReadyCallback callback) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if
// two "consecutive" `Ready() -> ();` calls are received, this interaction has entered an
// invalid state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
callback(fpromise::ok());
}
void handle_unknown_method(uint64_t ordinal, bool method_has_response) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something
// has changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client
// has not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = state_.bounding_box.top_left;
auto bottom_right = state_.bounding_box.bottom_right;
binding_.events().OnDrawn(top_left, bottom_right);
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change and ready trackers.
state_.ready = false;
state_.changed = false;
},
after);
}
fidl::Binding<examples::canvas::clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from
// the client. The following initializes the loop, and obtains the dispatcher, which will be
// used when binding the server implementation to a channel.
//
// Note that unlike the new C++ bindings, HLCPP bindings rely on the async loop being attached
// to the current thread via the |kAsyncLoopConfigAttachToCurrentThread| configuration.
async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component.
// This directory is where the outgoing FIDL protocols are installed so that they can be
// provided to other components.
auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
context->outgoing()->AddPublicService(
fidl::InterfaceRequestHandler<examples::canvas::clientrequesteddraw::Instance>(
[dispatcher](
fidl::InterfaceRequest<examples::canvas::clientrequesteddraw::Instance> request) {
// Create an instance of our |InstanceImpl| that destroys itself when the connection
// closes.
new InstanceImpl(dispatcher, std::move(request));
}));
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
生成的名称
FIDL 配方：生成的名称
生成的名称是为匿名类型的 FIDL 编译器分配的名称。虽然匿名类型在 FIDL 文件中本身是不可命名的，但在生成的绑定输出中必须有一个引用它们的名称，以便最终用户可以使用绑定语言创建该类型的实例。
由于 FIDL 编译器名称生成算法使用本地上下文（成员名称、方法名称等）来命名类型，因此可能会发生名称冲突。如需解决此类冲突，请直接在类型声明前面添加一个 @generated_name 属性，指示编译器应改用哪个名称。
在此变体中，我们允许键值对存储区将其他键值对存储区作为成员。简而言之，我们将其变成一棵树。为此，我们将 value 的原始定义替换为使用双成员 union 的定义：一个变体使用与之前相同的 vector<byte> 类型存储叶节点，而另一个变体以其他嵌套存储的形式存储分支节点。
推理
在这里，我们看到可选性的几种用途，我们可以借此声明一个可能存在或可能不存在的类型。FIDL 中有三种可选类型：
- 始终在线在线存储的类型，因此有一种内置方式，通过 null 信封来描述“缺失”。为这些类型启用可选性不会影响包含它们的消息的传输形状，而只是更改该特定类型有效的值。通过添加
:optional约束条件，union、vector<T>、client_end、server_end和zx.Handle类型均可设为可选类型。通过将valueunion设为可选，我们能够采用不存在的value的形式引入规范的“null”条目。这意味着空bytes和缺失/空store属性都是无效值。 - 与上述类型不同，
struct布局没有额外的空间可存储 null 标头。因此，需要将其封装在信封中，从而更改包含它的消息的线上形状。为了确保这种导线修改效果易于辨认，必须将Itemstruct类型封装在box<T>类型模板中。 - 最后，
table布局始终是可选的。如果table不存在，则只是未设置任何成员的标识符。
树是一种天生的自引用数据结构：树中的任何节点都可能包含具有纯数据的叶（在本例中为字符串）或具有更多节点的子树。这需要递归：Item 的定义现在以传递方式依赖于其本身！在 FIDL 中表示递归类型可能有点复杂，尤其是因为目前对支持的内容有些有限。只要自引用创建的周期中至少有一个可选类型，我们就可以支持此类类型。例如，在这里，我们将 items struct 成员定义为 box<Item>，从而打破包含循环。
这些更改还大量使用了匿名类型（即声明内嵌在其单一使用点的类型），而不是被命名的顶级 type 声明。默认情况下，生成的语言绑定中的匿名类型名称取自其本地上下文。例如，新引入的 flexible union 将采用其自有成员的名称 Value，新引入的 struct 将变为 Store，依此类推。由于这种启发式方法有时可能会导致冲突，因此 FIDL 提供了应急方法，允许作者手动替换匿名类型的生成名称。这是通过 @generated_name 属性实现的，该属性可用于更改后端生成的名称。我们可以在这里使用一个示例，将原本的 Store 类型重命名为 NestedStore，以防止名称与使用相同名称的 protocol 声明发生名称冲突。
实现
FIDL、CML 和 Realm 接口定义修改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supporttrees;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value strict union {
// Keep the original `bytes` as one of the options in the new union. All leaf nodes in the
// tree must be `bytes`, or absent unions (representing empty). Empty byte arrays are
// disallowed.
1: bytes vector<byte>:64000;
// Allows a store within a store, thereby turning our flat key-value store into a tree
// thereof. Note the use of `@generated_name` to prevent a type-name collision with the
// `Store` protocol below, and the use of `box<T>` to ensure that there is a break in the
// chain of recursion, thereby allowing `Item` to include itself in its own definition.
//
// This is a table so that added fields, like for example a `hash`, can be easily added in
// the future.
2: store @generated_name("nested_store") table {
1: items vector<box<Item>>;
};
}:optional;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A newline separated list nested entries. The first line should be the key
// for the nested store, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
write_nested: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A list of keys, all of which will be populated as null entries.
write_null: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_supporttrees::{Item, NestedStore, StoreMarker, Value},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
let res = store
.write_item(&Item {
key: key.clone(),
value: Some(Box::new(Value::Bytes(value.into_bytes()))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Add nested entries to the key-value store as well. The entries are strings, where the first
// line is the key of the entry, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
for spec in config.write_nested.into_iter() {
let mut items = vec![];
let mut nested_store = NestedStore::default();
let mut lines = spec.split("\n");
let key = lines.next().unwrap();
// For each entry, make a new entry in the `NestedStore` being built.
for entry in lines {
let path = format!("/pkg/data/{}.txt", entry);
let contents = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
items.push(Some(Box::new(Item {
key: entry.to_string(),
value: Some(Box::new(Value::Bytes(contents.into()))),
})));
}
nested_store.items = Some(items);
// Send the `NestedStore`, represented as a vector of values.
let res = store
.write_item(&Item {
key: key.to_string(),
value: Some(Box::new(Value::Store(nested_store))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Each entry in this list is a null value in the store.
for key in config.write_null.into_iter() {
match store.write_item(&Item { key: key.to_string(), value: None }).await? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_supporttrees::{
Item, StoreRequest, StoreRequestStream, Value, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
std::str::from_utf8,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
// A representation of a key-value store that can contain an arbitrarily deep nesting of other
// key-value stores.
#[allow(dead_code)] // TODO(https://fxbug.dev/318827209)
enum StoreNode {
Leaf(Option<Vec<u8>>),
Branch(Box<HashMap<String, StoreNode>>),
}
/// Recursive item writer, which takes a `StoreNode` that may not necessarily be the root node, and
/// writes an entry to it.
fn write_item(
store: &mut HashMap<String, StoreNode>,
attempt: Item,
path: &str,
) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
let key = format!("{}{}", &path, entry.key());
match attempt.value {
// Null entries are allowed.
None => {
println!("Wrote value: NONE at key: {}", key);
entry.insert(StoreNode::Leaf(None));
}
Some(value) => match *value {
// If this is a nested store, recursively make a new store to insert at this
// position.
Value::Store(entry_list) => {
// Validate the value - absent stores, items lists with no children, or any
// of the elements within that list being empty boxes, are all not allowed.
if entry_list.items.is_some() {
let items = entry_list.items.unwrap();
if !items.is_empty() && items.iter().all(|i| i.is_some()) {
let nested_path = format!("{}/", key);
let mut nested_store = HashMap::<String, StoreNode>::new();
for item in items.into_iter() {
write_item(&mut nested_store, *item.unwrap(), &nested_path)?;
}
println!("Created branch at key: {}", key);
entry.insert(StoreNode::Branch(Box::new(nested_store)));
return Ok(());
}
}
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
// This is a simple leaf node on this branch.
Value::Bytes(value) => {
// Validate the value.
if value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
println!("Wrote key: {}, value: {:?}", key, from_utf8(&value).unwrap());
entry.insert(StoreNode::Leaf(Some(value)));
}
},
}
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, StoreNode>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt, ""))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
处理权限
FIDL 方案：处理权利
FIDL 句柄表示某些系统（通常是 Zircon 内核）中的独特功能。标识名权限是对权能附带的权限的 FIDL 可辨识的枚举，例如，是否可以对标识名所代表的资源执行写入、检查和发送信号等操作。
权限在编码和解码时进行验证，以确保给定的句柄具有接口作者为其分配的一组权限。
扩展键值对存储区以支持导出备份的一种简单方法是，直接添加一个新方法来停止世界，对存储区的状态进行序列化，然后将其作为 FIDL vector<Item> 发送回。不过，这种方法有两个缺点。第一个是它将备份的所有负担都交给了服务器；对于请求服务器来说成本非常高昂的备份操作，客户端无需支付任何费用。其次，它涉及大量的复制操作：客户端几乎肯定会在收到备份后，立即将生成的备份写入某个后备数据存储区，如文件或数据库。让 FIDL 对象解码（可能非常大）FIDL 对象，以便它可以在将其转发到将执行实际存储的任何协议时立即对其重新编码，这非常浪费。
推理
更好的解决方案是使用 zircon 的虚拟内存对象。我们无需不断地在存储分区中来回复制字节，而是创建一个 VMO 来保存客户端上的备份数据，然后将备份数据发送到服务器，然后将其转发回我们的目标数据存储区，而无需在其间进行反序列化。只要目标数据存储区的协议允许接受使用 VMO 传输的数据，这就是完成此类成本高昂操作的首选方式。事实上，Fuchsia 的文件系统就实现了这种确切模式。这种方法的优势在于，在请求服务器执行开销大的操作时，它会强制客户端执行一些工作，从而最大限度地减少两方之间的工作不平衡。
可以使用 FIDL 数据持久性二进制格式将 FIDL 值类型持久存储到任何面向字节的存储媒介中。我们会将新引入的 FIDL 类型 Exportable 保留在 VMO 中。系统会对该对象进行编码和写入到存储空间（在本例中为稍后可保存为文件的 VMO），并在需要再次访问数据时通过该对象解码，这与稍后通过 IPC 使用 FIDL 再次对消息进行编码、传输和解码的方式大致相同。
为了安全地执行此操作并遵循最小权限原则，我们应该限制代表 VMO 的句柄可能具有的权限。输入处理程序权限，这是 FIDL 的一级方法，用于描述特定句柄类型可用的权限。在这种情况下，我们允许从 Export 请求中传递到服务器的 empty VMO 进行读取、查询大小、调整大小以及向其中写入数据。返回 VMO 后，我们将撤消调整大小和写入的权限，以确保在这些数据在系统中移动时，任何进程（甚至远处组件中的恶意操作者）都无法对其进行修改。
实现
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supportexports;
using zx;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value vector<byte>:64000;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to mint an export.
type ExportError = flexible enum {
UNKNOWN = 0;
EMPTY = 1;
STORAGE_TOO_SMALL = 2;
};
// A data type describing the structure of a single export. We never actually send this data type
// over the wire (we use the file's VMO instead), but whenever data needs to be written to/read from
// its backing storage as persistent FIDL, it will have this schema.
///
/// The items should be sorted in ascending order, following lexicographic ordering of their keys.
type Exportable = table {
1: items vector<Item>;
};
/// A very basic key-value store - so basic, in fact, that one may only write to it, never read!
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Exports the entire store as a persistent [`Exportable`] FIDL object into a VMO provided by
/// the client.
///
/// By having the client provide (and speculatively size) the VMO, we force the party requesting
/// the relatively heavy load of generating a backup to acknowledge and bear some of the costs.
///
/// This method operates by having the client supply an empty VMO, which the server then
/// attempts to fill. Notice that the server removes the `zx.Rights.WRITE` and
/// `zx.Rights.SET_PROPERTY` rights from the returned VMO - not even the requesting client may
/// alter the backup once it has been minted by the server.
flexible Export(resource struct {
/// Note that the empty VMO has more rights than the filled one being returned: it has
/// `zx.Rights.WRITE` (via `zx.RIGHTS_IO`) so that the VMO may be filled with exported data,
/// and `zx.Rights.SET_PROPERTY` (via `zx.RIGHTS_PROPERTY`) so that it may be resized to
/// truncate any remaining empty buffer.
empty zx.Handle:<VMO, zx.RIGHTS_BASIC | zx.RIGHTS_PROPERTY | zx.RIGHTS_IO>;
}) -> (resource struct {
/// The `zx.Rights.WRITE` and `zx.Rights.SET_PROPERTY` rights have been removed from the now
/// filled VMO. No one, not even the client that requested the export, is able to modify
/// this VMO going forward.
filled zx.Handle:<VMO, zx.RIGHTS_BASIC | zx.Rights.GET_PROPERTY | zx.Rights.READ>;
}) error ExportError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supportexports.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// The size, in bytes, allotted to the export VMO
max_export_size: { type: "uint64" },
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supportexports.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supportexports.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supportexports.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
use {
fidl::unpersist,
fidl_examples_keyvaluestore_supportexports::{Exportable, Item, StoreMarker},
fuchsia_zircon::Vmo,
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// If the `max_export_size` is 0, no export is possible, so just ignore this block. This check
// isn't strictly necessary, but does avoid extra work down the line.
if config.max_export_size > 0 {
// Create a 100Kb VMO to store the resulting export. In a real implementation, we would
// likely receive the VMO representing the to-be-written file from file system like vfs of
// fxfs.
let vmo = Vmo::create(config.max_export_size)?;
// Send the VMO to the server, to be populated with the current state of the key-value
// store.
match store.export(vmo).await? {
Err(err) => {
println!("Export Error: {}", err.into_primitive());
}
Ok(output) => {
println!("Export Success");
// Read the exported data (encoded in byte form as persistent FIDL) from the
// returned VMO. In a real implementation, instead of reading the VMO, we would
// merely forward it to some other storage-handling process. Doing this using a VMO,
// rather than FIDL IPC, would save us frivolous reads and writes at each hop.
let content_size = output.get_content_size().unwrap();
let mut encoded_bytes = vec![0; content_size as usize];
output.read(&mut encoded_bytes, 0)?;
// Decode the persistent FIDL that was just read from the file.
let exportable = unpersist::<Exportable>(&encoded_bytes).unwrap();
let items = exportable.items.expect("must always be set");
// Log some information about the exported data.
println!("Printing {} exported entries, which are:", items.len());
for item in items.iter() {
println!(" * {}", item.key);
}
}
};
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
use {
fidl::{persist, Vmo},
fidl_examples_keyvaluestore_supportexports::{
ExportError, Exportable, Item, StoreRequest, StoreRequestStream, WriteError,
},
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut HashMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Handler for the `Export` method.
fn export(store: &mut HashMap<String, Vec<u8>>, vmo: Vmo) -> Result<Vmo, ExportError> {
// Empty stores cannot be exported.
if store.is_empty() {
return Err(ExportError::Empty);
}
// Build the `Exportable` vector locally. That means iterating over the map, and turning it into
// a vector of items instead.
let mut exportable = Exportable::default();
let mut items = store
.iter()
.map(|entry| return Item { key: entry.0.clone(), value: entry.1.clone() })
.collect::<Vec<Item>>();
items.sort_by(|a, b| a.key.cmp(&b.key));
exportable.items = Some(items);
// Encode the bytes - there is a bug in persistent FIDL if this operation fails. Even if it
// succeeds, make sure to check that the VMO has enough space to handle the encoded export data.
let encoded_bytes = persist(&exportable).map_err(|_| ExportError::Unknown)?;
if encoded_bytes.len() as u64 > vmo.get_content_size().map_err(|_| ExportError::Unknown)? {
return Err(ExportError::StorageTooSmall);
}
// Write the (now encoded) persistent FIDL data to the VMO.
vmo.set_content_size(&(encoded_bytes.len() as u64)).map_err(|_| ExportError::Unknown)?;
vmo.write(&encoded_bytes, 0).map_err(|_| ExportError::Unknown)?;
Ok(vmo)
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Vec<u8>>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::Export { empty, responder } => {
println!("Export request received");
responder
.send(export(&mut store.borrow_mut(), empty))
.context("error sending reply")?;
println!("Export response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/fidl/new/key_value_store/support_exports/cpp_natural/client/config.h>
#include <src/lib/files/file.h>
#include <src/lib/fxl/strings/string_printf.h>
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_keyvaluestore_supportexports::Store>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Store| protocol: "
<< client_end.status_string();
return -1;
}
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.write_items()) {
std::string text;
if (!files::ReadFileToString(fxl::StringPrintf("/pkg/data/%s.txt", action.c_str()), &text)) {
FX_LOGS(ERROR) << "It looks like the correct `resource` dependency has not been packaged";
break;
}
auto value = std::vector<uint8_t>(text.begin(), text.end());
client->WriteItem(examples_keyvaluestore_supportexports::Item(action, value))
.ThenExactlyOnce(
[&](fidl::Result<examples_keyvaluestore_supportexports::Store::WriteItem> result) {
// Check if the FIDL call succeeded or not.
if (!result.is_ok()) {
if (result.error_value().is_framework_error()) {
FX_LOGS(ERROR) << "Unexpected FIDL framework error: " << result.error_value();
} else {
FX_LOGS(INFO) << "WriteItem Error: "
<< fidl::ToUnderlying(result.error_value().domain_error());
}
} else {
FX_LOGS(INFO) << "WriteItem Success";
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// If the `max_export_size` is 0, no export is possible, so just ignore this block. This check
// isn't strictly necessary, but does avoid extra work down the line.
if (conf.max_export_size() > 0) {
// Create a 100Kb VMO to store the resulting export. In a real implementation, we would
// likely receive the VMO representing the to-be-written file from file system like vfs of
// fxfs.
zx::vmo vmo;
if (zx_status_t status = zx::vmo::create(conf.max_export_size(), 0, &vmo); status != ZX_OK) {
FX_PLOGS(ERROR, status) << "Failed to create VMO";
return -1;
}
client->Export({std::move(vmo)})
.ThenExactlyOnce(
[&](fidl::Result<examples_keyvaluestore_supportexports::Store::Export>& result) {
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over, when we return from this callback.
loop.Quit();
if (!result.is_ok()) {
if (result.error_value().is_framework_error()) {
FX_LOGS(ERROR) << "Unexpected FIDL framework error: " << result.error_value();
} else {
FX_LOGS(INFO) << "Export Error: "
<< fidl::ToUnderlying(result.error_value().domain_error());
}
return;
}
FX_LOGS(INFO) << "Export Success";
// Read the exported data (encoded in byte form as persistent FIDL) from the
// returned VMO. In a real implementation, instead of reading the VMO, we would
// merely forward it to some other storage-handling process. Doing this using a VMO,
// rather than FIDL IPC, would save us frivolous reads and writes at each hop.
size_t content_size = 0;
zx::vmo vmo = std::move(result->filled());
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return;
}
std::vector<uint8_t> encoded_bytes;
encoded_bytes.resize(content_size);
if (vmo.read(encoded_bytes.data(), 0, content_size) != ZX_OK) {
return;
}
// Decode the persistent FIDL that was just read from the file.
fit::result exportable =
fidl::Unpersist<examples_keyvaluestore_supportexports::Exportable>(
cpp20::span(encoded_bytes));
if (exportable.is_error()) {
FX_LOGS(ERROR) << "Failed to unpersist: " << exportable.error_value();
return;
}
if (!exportable->items().has_value()) {
FX_LOGS(INFO) << "Expected items to be set";
return;
}
auto& items = exportable->items().value();
// Log some information about the exported data.
FX_LOGS(INFO) << "Printing " << items.size() << " exported entries, which are:";
for (const auto& item : items) {
FX_LOGS(INFO) << " * " << item.key();
}
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <algorithm>
#include <re2/re2.h>
// An implementation of the |Store| protocol.
class StoreImpl final : public fidl::Server<examples_keyvaluestore_supportexports::Store> {
public:
// Bind this implementation to a channel.
StoreImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](StoreImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})) {}
void WriteItem(WriteItemRequest& request, WriteItemCompleter::Sync& completer) override {
FX_LOGS(INFO) << "WriteItem request received";
auto key = request.attempt().key();
auto value = request.attempt().value();
// Validate the key.
if (!RE2::FullMatch(key, "^[A-Za-z]\\w+[A-Za-z0-9]$")) {
FX_LOGS(INFO) << "Write error: INVALID_KEY, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidKey));
}
// Validate the value.
if (value.empty()) {
FX_LOGS(INFO) << "Write error: INVALID_VALUE, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidValue));
}
if (key_value_store_.find(key) != key_value_store_.end()) {
FX_LOGS(INFO) << "Write error: ALREADY_EXISTS, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kAlreadyExists));
}
// Ensure that the value does not already exist in the store.
key_value_store_.insert({key, value});
FX_LOGS(INFO) << "Wrote value at key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(fit::ok());
}
void Export(ExportRequest& request, ExportCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Export request received";
completer.Reply(Export(std::move(request.empty())));
FX_LOGS(INFO) << "Export response sent";
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_keyvaluestore_supportexports::Store> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
using ExportError = ::examples_keyvaluestore_supportexports::ExportError;
using Exportable = ::examples_keyvaluestore_supportexports::Exportable;
using Item = ::examples_keyvaluestore_supportexports::Item;
fit::result<ExportError, zx::vmo> Export(zx::vmo vmo) {
if (key_value_store_.empty()) {
return fit::error(ExportError::kEmpty);
}
Exportable exportable;
std::vector<Item> items;
items.reserve(key_value_store_.size());
for (const auto& [k, v] : key_value_store_) {
items.push_back(Item{{.key = k, .value = v}});
}
std::sort(items.begin(), items.end(),
[](const Item& a, const Item& b) { return a.key() < b.key(); });
exportable.items(std::move(items));
fit::result encoded = fidl::Persist(exportable);
if (encoded.is_error()) {
FX_LOGS(ERROR) << "Failed to encode in persistence convention: " << encoded.error_value();
return fit::error(ExportError::kUnknown);
}
size_t content_size = 0;
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (encoded->size() > content_size) {
return fit::error(ExportError::kStorageTooSmall);
}
if (vmo.set_prop_content_size(encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (vmo.write(encoded->data(), 0, encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
return fit::ok(std::move(vmo));
}
fidl::ServerBindingRef<examples_keyvaluestore_supportexports::Store> binding_;
// The map that serves as the per-connection instance of the key-value store.
std::unordered_map<std::string, std::vector<uint8_t>> key_value_store_ = {};
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to |Store|.
result = outgoing.AddUnmanagedProtocol<examples_keyvaluestore_supportexports::Store>(
[dispatcher](fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
// Create an instance of our StoreImpl that destroys itself when the connection closes.
new StoreImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Store protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++（有线）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/fidl/new/key_value_store/support_exports/cpp_wire/client/config.h>
#include <src/lib/files/file.h>
#include <src/lib/fxl/strings/string_printf.h>
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_keyvaluestore_supportexports::Store>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Store| protocol: "
<< client_end.status_string();
return -1;
}
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& key : conf.write_items()) {
std::string text;
if (!files::ReadFileToString(fxl::StringPrintf("/pkg/data/%s.txt", key.c_str()), &text)) {
FX_LOGS(ERROR) << "It looks like the correct `resource` dependency has not been packaged";
break;
}
auto value = std::vector<uint8_t>(text.begin(), text.end());
client
->WriteItem(
{fidl::StringView::FromExternal(key), fidl::VectorView<uint8_t>::FromExternal(value)})
.ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_keyvaluestore_supportexports::Store::WriteItem>&
result) {
if (!result.ok()) {
FX_LOGS(ERROR) << "Unexpected framework error";
} else if (result->is_error()) {
FX_LOGS(INFO) << "WriteItem Error: " << fidl::ToUnderlying(result->error_value());
} else {
FX_LOGS(INFO) << "WriteItem Success";
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// If the `max_export_size` is 0, no export is possible, so just ignore this block. This check
// isn't strictly necessary, but does avoid extra work down the line.
if (conf.max_export_size() > 0) {
// Create a 100Kb VMO to store the resulting export. In a real implementation, we would
// likely receive the VMO representing the to-be-written file from file system like vfs of
// fxfs.
zx::vmo vmo;
if (zx_status_t status = zx::vmo::create(conf.max_export_size(), 0, &vmo); status != ZX_OK) {
FX_PLOGS(ERROR, status) << "Failed to create VMO";
return -1;
}
client->Export(std::move(vmo))
.ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_keyvaluestore_supportexports::Store::Export>&
result) {
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over, when we return from this callback.
loop.Quit();
if (!result.ok()) {
FX_LOGS(ERROR) << "Unexpected FIDL framework error: " << result.error();
return;
}
if (!result->is_ok()) {
FX_LOGS(INFO) << "Export Error: " << fidl::ToUnderlying(result->error_value());
return;
}
FX_LOGS(INFO) << "Export Success";
// Read the exported data (encoded in byte form as persistent FIDL) from the
// returned VMO. In a real implementation, instead of reading the VMO, we would
// merely forward it to some other storage-handling process. Doing this using a VMO,
// rather than FIDL IPC, would save us frivolous reads and writes at each hop.
size_t content_size = 0;
zx::vmo vmo = std::move(result->value()->filled);
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return;
}
std::vector<uint8_t> encoded_bytes;
encoded_bytes.resize(content_size);
if (vmo.read(encoded_bytes.data(), 0, content_size) != ZX_OK) {
return;
}
// Decode the persistent FIDL that was just read from the file.
fit::result exportable =
fidl::InplaceUnpersist<examples_keyvaluestore_supportexports::wire::Exportable>(
cpp20::span(encoded_bytes));
if (exportable.is_error()) {
FX_LOGS(ERROR) << "Failed to unpersist: " << exportable.error_value();
return;
}
if (!exportable->has_items()) {
FX_LOGS(INFO) << "Expected items to be set";
return;
}
auto& items = exportable->items();
// Log some information about the exported data.
FX_LOGS(INFO) << "Printing " << items.count() << " exported entries, which are:";
for (const auto& item : items) {
FX_LOGS(INFO) << " * " << item.key.get();
}
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <algorithm>
#include <re2/re2.h>
// An implementation of the |Store| protocol.
class StoreImpl final : public fidl::WireServer<examples_keyvaluestore_supportexports::Store> {
public:
// Bind this implementation to a channel.
StoreImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](StoreImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})) {}
void WriteItem(WriteItemRequestView request, WriteItemCompleter::Sync& completer) override {
FX_LOGS(INFO) << "WriteItem request received";
std::string key{request->attempt.key.get()};
std::vector<uint8_t> value{request->attempt.value.begin(), request->attempt.value.end()};
// Validate the key.
if (!RE2::FullMatch(key, "^[A-Za-z]\\w+[A-Za-z0-9]$")) {
FX_LOGS(INFO) << "Write error: INVALID_KEY, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidKey));
}
// Validate the value.
if (value.empty()) {
FX_LOGS(INFO) << "Write error: INVALID_VALUE, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidValue));
}
if (key_value_store_.find(key) != key_value_store_.end()) {
FX_LOGS(INFO) << "Write error: ALREADY_EXISTS, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kAlreadyExists));
}
// Ensure that the value does not already exist in the store.
key_value_store_.insert({key, value});
FX_LOGS(INFO) << "Wrote value at key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(fit::success());
}
void Export(ExportRequestView request, ExportCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Export request received";
fit::result result = Export(std::move(request->empty));
if (result.is_ok()) {
completer.ReplySuccess(std::move(result.value()));
} else {
completer.ReplyError(result.error_value());
}
FX_LOGS(INFO) << "Export response sent";
}
using ExportError = ::examples_keyvaluestore_supportexports::wire::ExportError;
using Exportable = ::examples_keyvaluestore_supportexports::wire::Exportable;
using Item = ::examples_keyvaluestore_supportexports::wire::Item;
fit::result<ExportError, zx::vmo> Export(zx::vmo vmo) {
if (key_value_store_.empty()) {
return fit::error(ExportError::kEmpty);
}
fidl::Arena arena;
fidl::VectorView<Item> items;
items.Allocate(arena, key_value_store_.size());
size_t count = 0;
for (auto& [k, v] : key_value_store_) {
// Create a wire |Item| object that borrows from |k| and |v|.
// Since |k| and |v| are references into the long living |key_value_store_|,
// while |items| only live within the current function scope,
// this operation is safe.
items[count] = Item{
.key = fidl::StringView::FromExternal(k),
.value = fidl::VectorView<uint8_t>::FromExternal(v),
};
count++;
}
std::sort(items.begin(), items.end(),
[](const Item& a, const Item& b) { return a.key.get() < b.key.get(); });
Exportable exportable = Exportable::Builder(arena).items(items).Build();
fit::result encoded = fidl::Persist(exportable);
if (encoded.is_error()) {
FX_LOGS(ERROR) << "Failed to encode in persistence convention: " << encoded.error_value();
return fit::error(ExportError::kUnknown);
}
size_t content_size = 0;
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (encoded->size() > content_size) {
return fit::error(ExportError::kStorageTooSmall);
}
if (vmo.set_prop_content_size(encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (vmo.write(encoded->data(), 0, encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
return fit::ok(std::move(vmo));
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_keyvaluestore_supportexports::Store> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
fidl::ServerBindingRef<examples_keyvaluestore_supportexports::Store> binding_;
// The map that serves as the per-connection instance of the key-value store.
//
// Out-of-line references in wire types are always mutable. Thus the
// |const std::vector<uint8_t>| from the baseline needs to be changed to
// non-const as we're making a vector view pointing to it during |Export|,
// even though in practice the value is never mutated.
std::unordered_map<std::string, std::vector<uint8_t>> key_value_store_ = {};
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to |Store|.
result = outgoing.AddUnmanagedProtocol<examples_keyvaluestore_supportexports::Store>(
[dispatcher](fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
// Create an instance of our StoreImpl that destroys itself when the connection closes.
new StoreImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Store protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
不会出错的双向方法
FIDL 配方：不可靠的双向方法
不可靠的双向方法是指无法返回错误值的 FIDL 方法。唯一可能的故障模式是底层渠道出现故障（如无法连接到其中一个端点）。
在此示例中，您将创建一个基本的计算器服务器和客户端，该服务器和客户端显示了首先定义然后传送和使用 FIDL 协议所需的基本设置。
首先，您需要定义接口定义和自动化测试框架。接口定义（.fidl 文件本身）是所有新 FIDL 协议的起点。此外，该计算器包含创建客户端-服务器模式所需的 CML 和领域定义，这些模式可用作任意实现的项目基架。
FIDL 代码如下所示：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// The namespace for this FIDL protocol. This namespace is how both consumers (clients) and providers (servers) reference this protocol.
library examples.calculator.baseline;
// @discoverable indicates 'Calculator' is a protocol that will be served under the examples.calculator.baseline libarary namespace. https://fuchsia.dev/fuchsia-src/reference/fidl/language/attributes#discoverable . If @discoverable is missing, it will lead to a compile time error when trying to import the library.
@discoverable
// A limited-functionality calculator 'protocol' that adds and subtracts integers.
open protocol Calculator {
// Takes as input a struct with two integers, and returns their sum: (a+b)=sum. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Add(struct {
a int32;
b int32;
}) -> (struct {
sum int64;
});
// Takes as input a struct with two integers, and returns their difference: (a-b)=difference. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Subtract(struct {
a int32;
b int32;
}) -> (struct {
difference int64;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
config: {},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
expose: [
{
protocol: "examples.calculator.baseline.Calculator",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.calculator.baseline.Calculator",
from: "#server",
to: "#client",
},
// Route logging support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// TODO(https://fxbug.dev/42063075): Rust implementation.
服务器
// TODO(https://fxbug.dev/42063075): Rust implementation.
C++（自然）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
对于某些开发者（例如平台开发者）来说，从头开始创建 FIDL 协议（如此示例所示）可能是更常见的场景。不过，其他类型的开发者也可以受益于学习如何构造 FIDL 协议（即使他们通常不会这样做）。这有助于您了解 FIDL 的所有要素，包括语法、语法、语言功能、如何提供和使用给定 FIDL 协议，以及构建系统的工作原理。对于后续步骤，此基准后面的示例展示了如何扩展现有的 FIDL 协议，这应该是一种相当常见的做法。
已命名的载荷
FIDL 配方：命名载荷
命名载荷是直接用作方法请求或响应载荷的 struct、table 或 union 类型。如果方法载荷是重复的，或已经是 FIDL 文件中其他位置使用的已命名类型，则可以使用这些类型。
在以下示例中，添加的 ReadItem 方法与现有 WriteItem 明显不同，它使用现有的已命名类型作为载荷，而不是使用重复的内嵌定义。
推理
原来的只写键值对存储区现已扩展，能够从存储区中读回项。
实现
对 FIDL 和 CML 定义的更改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.addreaditem;
// Aliases for the key and value. Using aliases helps increase the readability of FIDL files and
// reduces likelihood of errors due to differing constraints.
alias Key = string:128;
alias Value = vector<byte>:64000;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key Key;
value Value;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to read a value out of our store.
type ReadError = flexible enum {
UNKNOWN = 0;
NOT_FOUND = 1;
};
/// A very basic key-value store - so basic, in fact, that one may only write to it, never read!
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Reads an item from the store.
flexible ReadItem(struct {
key Key;
}) -> (Item) error ReadError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.addreaditem.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
read_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.addreaditem.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.addreaditem.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.addreaditem.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
所有语言的客户端和服务器实现也会发生变化：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_addreaditem::{Item, StoreMarker},
fuchsia_component::client::connect_to_protocol,
std::{str, thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// The structured config for this client contains `read_items`, a vector of strings, each of
// which is meant to be read from the key-value store. We iterate over these keys, attempting to
// read them in turn.
for key in config.read_items.into_iter() {
let res = store.read_item(key.as_str()).await;
match res.unwrap() {
Ok(val) => {
println!("ReadItem Success: key: {}, value: {}", key, str::from_utf8(&val.1)?)
}
Err(err) => println!("ReadItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_addreaditem::{
Item, ReadError, StoreRequest, StoreRequestStream, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z][A-Za-z0-9_\./]{2,62}[A-Za-z0-9]$")
.expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut HashMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Vec<u8>>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::ReadItem { key, responder } => {
println!("ReadItem request received");
// Read the item from the store, returning the appropriate error if it could not be found.
responder
.send(match store.borrow().get(&key) {
Some(found) => {
println!("Read value at key: {}", key);
Ok((&key, found))
}
None => {
println!("Read error: NOT_FOUND, For key: {}", key);
Err(ReadError::NotFound)
}
})
.context("error sending reply")?;
println!("ReadItem response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
可选性
FIDL 配方：可选
某些 FIDL 类型可以设置为可选，添加 :optional 限制后，不更改其包含消息的线形。此外，table 布局始终是可选的，而 struct 布局从不。如需使 struct 成为可选，它必须封装在 box<T> 中，从而更改其包含消息的线形。
| 基本类型 | 可选版本 | 可选性是否会改变线路布局？ |
|---|---|---|
struct {...} |
box<struct {...}> |
是 |
table {...} |
table {...} |
否 |
union {...} |
union {...}:optional |
否 |
vector<T> |
vector<T>:optional |
否 |
string |
string:optional |
否 |
zx.Handle |
zx.Handle:optional |
否 |
client_end:P |
client_end:<P, optional> |
否 |
server_end:P |
server_end:<P, optional> |
否 |
所有其他类型（bits、enum、array<T, N> 和基元类型）都不能设为可选类型。
在此变体中，我们允许键值对存储区将其他键值对存储区作为成员。简而言之，我们将其变成一棵树。为此，我们将 value 的原始定义替换为使用双成员 union 的定义：一个变体使用与之前相同的 vector<byte> 类型存储叶节点，而另一个变体以其他嵌套存储的形式存储分支节点。
推理
在这里，我们看到可选性的几种用途，我们可以借此声明一个可能存在或可能不存在的类型。FIDL 中有三种可选类型：
- 始终在线在线存储的类型，因此有一种内置方式，通过 null 信封来描述“缺失”。为这些类型启用可选性不会影响包含它们的消息的传输形状，而只是更改该特定类型有效的值。通过添加
:optional约束条件，union、vector<T>、client_end、server_end和zx.Handle类型均可设为可选类型。通过将valueunion设为可选，我们能够采用不存在的value的形式引入规范的“null”条目。这意味着空bytes和缺失/空store属性都是无效值。 - 与上述类型不同，
struct布局没有额外的空间可存储 null 标头。因此，需要将其封装在信封中，从而更改包含它的消息的线上形状。为了确保这种导线修改效果易于辨认，必须将Itemstruct类型封装在box<T>类型模板中。 - 最后，
table布局始终是可选的。如果table不存在，则只是未设置任何成员的标识符。
树是一种天生的自引用数据结构：树中的任何节点都可能包含具有纯数据的叶（在本例中为字符串）或具有更多节点的子树。这需要递归：Item 的定义现在以传递方式依赖于其本身！在 FIDL 中表示递归类型可能有点复杂，尤其是因为目前对支持的内容有些有限。只要自引用创建的周期中至少有一个可选类型，我们就可以支持此类类型。例如，在这里，我们将 items struct 成员定义为 box<Item>，从而打破包含循环。
这些更改还大量使用了匿名类型（即声明内嵌在其单一使用点的类型），而不是被命名的顶级 type 声明。默认情况下，生成的语言绑定中的匿名类型名称取自其本地上下文。例如，新引入的 flexible union 将采用其自有成员的名称 Value，新引入的 struct 将变为 Store，依此类推。由于这种启发式方法有时可能会导致冲突，因此 FIDL 提供了应急方法，允许作者手动替换匿名类型的生成名称。这是通过 @generated_name 属性实现的，该属性可用于更改后端生成的名称。我们可以在这里使用一个示例，将原本的 Store 类型重命名为 NestedStore，以防止名称与使用相同名称的 protocol 声明发生名称冲突。
实现
FIDL、CML 和 Realm 接口定义修改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supporttrees;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value strict union {
// Keep the original `bytes` as one of the options in the new union. All leaf nodes in the
// tree must be `bytes`, or absent unions (representing empty). Empty byte arrays are
// disallowed.
1: bytes vector<byte>:64000;
// Allows a store within a store, thereby turning our flat key-value store into a tree
// thereof. Note the use of `@generated_name` to prevent a type-name collision with the
// `Store` protocol below, and the use of `box<T>` to ensure that there is a break in the
// chain of recursion, thereby allowing `Item` to include itself in its own definition.
//
// This is a table so that added fields, like for example a `hash`, can be easily added in
// the future.
2: store @generated_name("nested_store") table {
1: items vector<box<Item>>;
};
}:optional;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A newline separated list nested entries. The first line should be the key
// for the nested store, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
write_nested: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A list of keys, all of which will be populated as null entries.
write_null: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_supporttrees::{Item, NestedStore, StoreMarker, Value},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
let res = store
.write_item(&Item {
key: key.clone(),
value: Some(Box::new(Value::Bytes(value.into_bytes()))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Add nested entries to the key-value store as well. The entries are strings, where the first
// line is the key of the entry, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
for spec in config.write_nested.into_iter() {
let mut items = vec![];
let mut nested_store = NestedStore::default();
let mut lines = spec.split("\n");
let key = lines.next().unwrap();
// For each entry, make a new entry in the `NestedStore` being built.
for entry in lines {
let path = format!("/pkg/data/{}.txt", entry);
let contents = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
items.push(Some(Box::new(Item {
key: entry.to_string(),
value: Some(Box::new(Value::Bytes(contents.into()))),
})));
}
nested_store.items = Some(items);
// Send the `NestedStore`, represented as a vector of values.
let res = store
.write_item(&Item {
key: key.to_string(),
value: Some(Box::new(Value::Store(nested_store))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Each entry in this list is a null value in the store.
for key in config.write_null.into_iter() {
match store.write_item(&Item { key: key.to_string(), value: None }).await? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_supporttrees::{
Item, StoreRequest, StoreRequestStream, Value, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
std::str::from_utf8,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
// A representation of a key-value store that can contain an arbitrarily deep nesting of other
// key-value stores.
#[allow(dead_code)] // TODO(https://fxbug.dev/318827209)
enum StoreNode {
Leaf(Option<Vec<u8>>),
Branch(Box<HashMap<String, StoreNode>>),
}
/// Recursive item writer, which takes a `StoreNode` that may not necessarily be the root node, and
/// writes an entry to it.
fn write_item(
store: &mut HashMap<String, StoreNode>,
attempt: Item,
path: &str,
) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
let key = format!("{}{}", &path, entry.key());
match attempt.value {
// Null entries are allowed.
None => {
println!("Wrote value: NONE at key: {}", key);
entry.insert(StoreNode::Leaf(None));
}
Some(value) => match *value {
// If this is a nested store, recursively make a new store to insert at this
// position.
Value::Store(entry_list) => {
// Validate the value - absent stores, items lists with no children, or any
// of the elements within that list being empty boxes, are all not allowed.
if entry_list.items.is_some() {
let items = entry_list.items.unwrap();
if !items.is_empty() && items.iter().all(|i| i.is_some()) {
let nested_path = format!("{}/", key);
let mut nested_store = HashMap::<String, StoreNode>::new();
for item in items.into_iter() {
write_item(&mut nested_store, *item.unwrap(), &nested_path)?;
}
println!("Created branch at key: {}", key);
entry.insert(StoreNode::Branch(Box::new(nested_store)));
return Ok(());
}
}
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
// This is a simple leaf node on this branch.
Value::Bytes(value) => {
// Validate the value.
if value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
println!("Wrote key: {}, value: {:?}", key, from_utf8(&value).unwrap());
entry.insert(StoreNode::Leaf(Some(value)));
}
},
}
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, StoreNode>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt, ""))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
分页模式
FIDL 诀窍：分页模式
在发送可能会非常大的项列表时，一种实用策略是通过分页模式将该列表分解为多次调用。使用分页可在发送者和接收者之间实现更精细的工作同步：发送者一次发出一些内容，并等待消息已处理完成的反馈，而不是大量列表来强迫接收方。
用 FIDL 术语来说，这意味着 FIDL 作者应将其转换为 vector<T>:N 确认消息，以确保页面大小和流控制是 FIDL 协定的一部分，而不是发送单个大型 vector<T>。
对键值对存储非常有用的一个操作是按顺序迭代：也就是说，在给定键时，可按顺序返回显示在该键后面的元素列表（通常会分页）。
推理
在 FIDL 中，最好使用迭代器来实现此目的，该迭代器通常作为可以发生此迭代的单独协议来实现。使用单独的协议因此使用单独的通道有许多好处，包括消除通过主协议执行的其他操作中的迭代拉取请求。
协议 P 的通道连接的客户端和服务器端可以分别表示为 FIDL 数据类型，分别表示为 client_end:P 和 server_end:P。这些类型统称为协议端，表示将 FIDL 客户端连接到其相应服务器的另一种（非 @discoverable）方式：通过现有的 FIDL 连接！
协议结尾是一般 FIDL 概念（即资源类型）的特定实例。资源类型包含 FIDL 句柄，因此需要对类型的使用方式做出额外限制。类型必须始终是唯一的，因为底层资源由其他 capability 管理器（通常是 Zircon 内核）进行中介。在不涉及管理器的情况下，通过简单的内存中复制来复制此类资源是不可能的。为防止此类重复，FIDL 中的所有资源类型始终都是只能移动的资源类型。
最后，Iterator 协议本身的 Get() 方法对返回载荷使用大小限制。这限制了在单次拉取中可能传输的数据量，让您可以在一定程度上控制资源使用。这还会创建自然的分页边界：服务器只需一次准备小批量，而不是一次性生成所有结果的巨型转储。
实现
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.additerator;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value vector<byte>:64000;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to create an iterator.
type IterateConnectionError = flexible enum {
/// The starting key was not found.
UNKNOWN_START_AT = 1;
};
/// A key-value store which supports insertion and iteration.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Iterates over the items in the store, using lexicographic ordering over the keys.
///
/// The [`iterator`] is [pipelined][pipelining] to the server, such that the client can
/// immediately send requests over the new connection.
///
/// [pipelining]: https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#request-pipelining
flexible Iterate(resource struct {
/// If present, requests to start the iteration at this item.
starting_at string:<128, optional>;
/// The [`Iterator`] server endpoint. The client creates both ends of the channel and
/// retains the `client_end` locally to use for pulling iteration pages, while sending the
/// `server_end` off to be fulfilled by the server.
iterator server_end:Iterator;
}) -> () error IterateConnectionError;
};
/// An iterator for the key-value store. Note that this protocol makes no guarantee of atomicity -
/// the values may change between pulls from the iterator. Unlike the `Store` protocol above, this
/// protocol is not `@discoverable`: it is not independently published by the component that
/// implements it, but rather must have one of its two protocol ends transmitted over an existing
/// FIDL connection.
///
/// As is often the case with iterators, the client indicates that they are done with an instance of
/// the iterator by simply closing their end of the connection.
///
/// Since the iterator is associated only with the Iterate method, it is declared as closed rather
/// than open. This is because changes to how iteration works are more likely to require replacing
/// the Iterate method completely (which is fine because that method is flexible) rather than
/// evolving the Iterator protocol.
closed protocol Iterator {
/// Gets the next batch of keys.
///
/// The client pulls keys rather than having the server proactively push them, to implement
/// [flow control][flow-control] over the messages.
///
/// [flow-control]:
/// https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#prefer_pull_to_push
strict Get() -> (struct {
/// A list of keys. If the iterator has reached the end of iteration, the list will be
/// empty. The client is expected to then close the connection.
entries vector<string:128>:10;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A key to iterate from, after all items in `write_items` have been written.
iterate_from: {
type: "string",
max_size: 64,
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
use {
fidl::endpoints::create_proxy,
fidl_examples_keyvaluestore_additerator::{Item, IteratorMarker, StoreMarker},
futures::join,
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
if !config.iterate_from.is_empty() {
// This helper creates a channel, and returns two protocol ends: the `client_end` is already
// conveniently bound to the correct FIDL protocol, `Iterator`, while the `server_end` is
// unbound and ready to be sent over the wire.
let (iterator, server_end) = create_proxy::<IteratorMarker>()?;
// There is no need to wait for the iterator to connect before sending the first `Get()`
// request - since we already hold the `client_end` of the connection, we can start queuing
// requests on it immediately.
let connect_to_iterator = store.iterate(Some(config.iterate_from.as_str()), server_end);
let first_get = iterator.get();
// Wait until both the connection and the first request resolve - an error in either case
// triggers an immediate resolution of the combined future.
let (connection, first_page) = join!(connect_to_iterator, first_get);
// Handle any connection error. If this has occurred, it is impossible for the first `Get()`
// call to have resolved successfully, so check this error first.
if let Err(err) = connection.context("Could not connect to Iterator")? {
println!("Iterator Connection Error: {}", err.into_primitive());
} else {
println!("Iterator Connection Success");
// Consecutively repeat the `Get()` request if the previous response was not empty.
let mut entries = first_page.context("Could not get page from Iterator")?;
while !&entries.is_empty() {
for entry in entries.iter() {
println!("Iterator Entry: {}", entry);
}
entries = iterator.get().await.context("Could not get page from Iterator")?;
}
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
};
use {
fidl_examples_keyvaluestore_additerator::{
Item, IterateConnectionError, IteratorRequest, IteratorRequestStream, StoreRequest,
StoreRequestStream, WriteError,
},
fuchsia_async as fasync,
std::collections::btree_map::Entry,
std::collections::BTreeMap,
std::ops::Bound::*,
std::sync::Arc,
std::sync::Mutex,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut BTreeMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Handler for the `Iterate` method, which deals with validating that the requested start position
/// exists, and then sets up the asynchronous side channel for the actual iteration to occur over.
fn iterate(
store: Arc<Mutex<BTreeMap<String, Vec<u8>>>>,
starting_at: Option<String>,
stream: IteratorRequestStream,
) -> Result<(), IterateConnectionError> {
// Validate that the starting key, if supplied, actually exists.
if let Some(start_key) = starting_at.clone() {
if !store.lock().unwrap().contains_key(&start_key) {
return Err(IterateConnectionError::UnknownStartAt);
}
}
// Spawn a detached task. This allows the method call to return while the iteration continues in
// a separate, unawaited task.
fasync::Task::spawn(async move {
// Serve the iteration requests. Note that access to the underlying store is behind a
// contended `Mutex`, meaning that the iteration is not atomic: page contents could shift,
// change, or disappear entirely between `Get()` requests.
stream
.map(|result| result.context("failed request"))
.try_fold(
match starting_at {
Some(start_key) => Included(start_key),
None => Unbounded,
},
|mut lower_bound, request| async {
match request {
IteratorRequest::Get { responder } => {
println!("Iterator page request received");
// The `page_size` should be kept in sync with the size constraint on
// the iterator's response, as defined in the FIDL protocol.
static PAGE_SIZE: usize = 10;
// An iterator, beginning at `lower_bound` and tracking the pagination's
// progress through iteration as each page is pulled by a client-sent
// `Get()` request.
let held_store = store.lock().unwrap();
let mut entries = held_store.range((lower_bound.clone(), Unbounded));
let mut current_page = vec![];
for _ in 0..PAGE_SIZE {
match entries.next() {
Some(entry) => {
current_page.push(entry.0.clone());
}
None => break,
}
}
// Update the `lower_bound` - either inclusive of the next item in the
// iteration, or exclusive of the last seen item if the iteration has
// finished. This `lower_bound` will be passed to the next request
// handler as its starting point.
lower_bound = match entries.next() {
Some(next) => Included(next.0.clone()),
None => match current_page.last() {
Some(tail) => Excluded(tail.clone()),
None => lower_bound,
},
};
// Send the page. At the end of this scope, the `held_store` lock gets
// dropped, and therefore released.
responder.send(¤t_page).context("error sending reply")?;
println!("Iterator page sent");
}
}
Ok(lower_bound)
},
)
.await
.ok();
})
.detach();
Ok(())
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
//
// Note that we now use an `Arc<Mutex<BTreeMap>>`, replacing the previous `RefCell<HashMap>`.
// The `BTreeMap` is used because we want an ordered map, to better facilitate iteration. The
// `Arc<Mutex<...>>` is used because there are now multiple async tasks accessing the: one main
// task which handles communication over the protocol, and one additional task per iterator
// protocol. `Arc<Mutex<...>>` is the simplest way to synchronize concurrent access between
// these racing tasks.
let store = &Arc::new(Mutex::new(BTreeMap::<String, Vec<u8>>::new()));
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.clone().lock().unwrap(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::Iterate { starting_at, iterator, responder } => {
println!("Iterate request received");
// The `iterate` handler does a quick check to see that the request is valid,
// then spins up a separate worker task to serve the newly minted `Iterator`
// protocol instance, allowing this call to return immediately and continue the
// request stream with other work.
responder
.send(iterate(store.clone(), starting_at, iterator.into_stream()?))
.context("error sending reply")?;
println!("Iterate response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
持久性
FIDL 配方：持久性
永久性 FIDL 是指在没有底层传输的情况下存储的采用有线编码的二进制 FIDL 数据。而是使用面向字节的永久性接口（如文件或数据库条目）将数据存储在任意时长的时间段内。
扩展键值对存储区以支持导出备份的一种简单方法是，直接添加一个新方法来停止世界，对存储区的状态进行序列化，然后将其作为 FIDL vector<Item> 发送回。不过，这种方法有两个缺点。第一个是它将备份的所有负担都交给了服务器；对于请求服务器来说成本非常高昂的备份操作，客户端无需支付任何费用。其次，它涉及大量的复制操作：客户端几乎肯定会在收到备份后，立即将生成的备份写入某个后备数据存储区，如文件或数据库。让 FIDL 对象解码（可能非常大）FIDL 对象，以便它可以在将其转发到将执行实际存储的任何协议时立即对其重新编码，这非常浪费。
推理
更好的解决方案是使用 zircon 的虚拟内存对象。我们无需不断地在存储分区中来回复制字节，而是创建一个 VMO 来保存客户端上的备份数据，然后将备份数据发送到服务器，然后将其转发回我们的目标数据存储区，而无需在其间进行反序列化。只要目标数据存储区的协议允许接受使用 VMO 传输的数据，这就是完成此类成本高昂操作的首选方式。事实上，Fuchsia 的文件系统就实现了这种确切模式。这种方法的优势在于，在请求服务器执行开销大的操作时，它会强制客户端执行一些工作，从而最大限度地减少两方之间的工作不平衡。
可以使用 FIDL 数据持久性二进制格式将 FIDL 值类型持久存储到任何面向字节的存储媒介中。我们会将新引入的 FIDL 类型 Exportable 保留在 VMO 中。系统会对该对象进行编码和写入到存储空间（在本例中为稍后可保存为文件的 VMO），并在需要再次访问数据时通过该对象解码，这与稍后通过 IPC 使用 FIDL 再次对消息进行编码、传输和解码的方式大致相同。
为了安全地执行此操作并遵循最小权限原则，我们应该限制代表 VMO 的句柄可能具有的权限。输入处理程序权限，这是 FIDL 的一级方法，用于描述特定句柄类型可用的权限。在这种情况下，我们允许从 Export 请求中传递到服务器的 empty VMO 进行读取、查询大小、调整大小以及向其中写入数据。返回 VMO 后，我们将撤消调整大小和写入的权限，以确保在这些数据在系统中移动时，任何进程（甚至远处组件中的恶意操作者）都无法对其进行修改。
实现
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supportexports;
using zx;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value vector<byte>:64000;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to mint an export.
type ExportError = flexible enum {
UNKNOWN = 0;
EMPTY = 1;
STORAGE_TOO_SMALL = 2;
};
// A data type describing the structure of a single export. We never actually send this data type
// over the wire (we use the file's VMO instead), but whenever data needs to be written to/read from
// its backing storage as persistent FIDL, it will have this schema.
///
/// The items should be sorted in ascending order, following lexicographic ordering of their keys.
type Exportable = table {
1: items vector<Item>;
};
/// A very basic key-value store - so basic, in fact, that one may only write to it, never read!
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Exports the entire store as a persistent [`Exportable`] FIDL object into a VMO provided by
/// the client.
///
/// By having the client provide (and speculatively size) the VMO, we force the party requesting
/// the relatively heavy load of generating a backup to acknowledge and bear some of the costs.
///
/// This method operates by having the client supply an empty VMO, which the server then
/// attempts to fill. Notice that the server removes the `zx.Rights.WRITE` and
/// `zx.Rights.SET_PROPERTY` rights from the returned VMO - not even the requesting client may
/// alter the backup once it has been minted by the server.
flexible Export(resource struct {
/// Note that the empty VMO has more rights than the filled one being returned: it has
/// `zx.Rights.WRITE` (via `zx.RIGHTS_IO`) so that the VMO may be filled with exported data,
/// and `zx.Rights.SET_PROPERTY` (via `zx.RIGHTS_PROPERTY`) so that it may be resized to
/// truncate any remaining empty buffer.
empty zx.Handle:<VMO, zx.RIGHTS_BASIC | zx.RIGHTS_PROPERTY | zx.RIGHTS_IO>;
}) -> (resource struct {
/// The `zx.Rights.WRITE` and `zx.Rights.SET_PROPERTY` rights have been removed from the now
/// filled VMO. No one, not even the client that requested the export, is able to modify
/// this VMO going forward.
filled zx.Handle:<VMO, zx.RIGHTS_BASIC | zx.Rights.GET_PROPERTY | zx.Rights.READ>;
}) error ExportError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supportexports.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// The size, in bytes, allotted to the export VMO
max_export_size: { type: "uint64" },
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supportexports.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supportexports.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supportexports.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
use {
fidl::unpersist,
fidl_examples_keyvaluestore_supportexports::{Exportable, Item, StoreMarker},
fuchsia_zircon::Vmo,
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// If the `max_export_size` is 0, no export is possible, so just ignore this block. This check
// isn't strictly necessary, but does avoid extra work down the line.
if config.max_export_size > 0 {
// Create a 100Kb VMO to store the resulting export. In a real implementation, we would
// likely receive the VMO representing the to-be-written file from file system like vfs of
// fxfs.
let vmo = Vmo::create(config.max_export_size)?;
// Send the VMO to the server, to be populated with the current state of the key-value
// store.
match store.export(vmo).await? {
Err(err) => {
println!("Export Error: {}", err.into_primitive());
}
Ok(output) => {
println!("Export Success");
// Read the exported data (encoded in byte form as persistent FIDL) from the
// returned VMO. In a real implementation, instead of reading the VMO, we would
// merely forward it to some other storage-handling process. Doing this using a VMO,
// rather than FIDL IPC, would save us frivolous reads and writes at each hop.
let content_size = output.get_content_size().unwrap();
let mut encoded_bytes = vec![0; content_size as usize];
output.read(&mut encoded_bytes, 0)?;
// Decode the persistent FIDL that was just read from the file.
let exportable = unpersist::<Exportable>(&encoded_bytes).unwrap();
let items = exportable.items.expect("must always be set");
// Log some information about the exported data.
println!("Printing {} exported entries, which are:", items.len());
for item in items.iter() {
println!(" * {}", item.key);
}
}
};
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
use {
fidl::{persist, Vmo},
fidl_examples_keyvaluestore_supportexports::{
ExportError, Exportable, Item, StoreRequest, StoreRequestStream, WriteError,
},
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut HashMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Handler for the `Export` method.
fn export(store: &mut HashMap<String, Vec<u8>>, vmo: Vmo) -> Result<Vmo, ExportError> {
// Empty stores cannot be exported.
if store.is_empty() {
return Err(ExportError::Empty);
}
// Build the `Exportable` vector locally. That means iterating over the map, and turning it into
// a vector of items instead.
let mut exportable = Exportable::default();
let mut items = store
.iter()
.map(|entry| return Item { key: entry.0.clone(), value: entry.1.clone() })
.collect::<Vec<Item>>();
items.sort_by(|a, b| a.key.cmp(&b.key));
exportable.items = Some(items);
// Encode the bytes - there is a bug in persistent FIDL if this operation fails. Even if it
// succeeds, make sure to check that the VMO has enough space to handle the encoded export data.
let encoded_bytes = persist(&exportable).map_err(|_| ExportError::Unknown)?;
if encoded_bytes.len() as u64 > vmo.get_content_size().map_err(|_| ExportError::Unknown)? {
return Err(ExportError::StorageTooSmall);
}
// Write the (now encoded) persistent FIDL data to the VMO.
vmo.set_content_size(&(encoded_bytes.len() as u64)).map_err(|_| ExportError::Unknown)?;
vmo.write(&encoded_bytes, 0).map_err(|_| ExportError::Unknown)?;
Ok(vmo)
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Vec<u8>>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::Export { empty, responder } => {
println!("Export request received");
responder
.send(export(&mut store.borrow_mut(), empty))
.context("error sending reply")?;
println!("Export response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/fidl/new/key_value_store/support_exports/cpp_natural/client/config.h>
#include <src/lib/files/file.h>
#include <src/lib/fxl/strings/string_printf.h>
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_keyvaluestore_supportexports::Store>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Store| protocol: "
<< client_end.status_string();
return -1;
}
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.write_items()) {
std::string text;
if (!files::ReadFileToString(fxl::StringPrintf("/pkg/data/%s.txt", action.c_str()), &text)) {
FX_LOGS(ERROR) << "It looks like the correct `resource` dependency has not been packaged";
break;
}
auto value = std::vector<uint8_t>(text.begin(), text.end());
client->WriteItem(examples_keyvaluestore_supportexports::Item(action, value))
.ThenExactlyOnce(
[&](fidl::Result<examples_keyvaluestore_supportexports::Store::WriteItem> result) {
// Check if the FIDL call succeeded or not.
if (!result.is_ok()) {
if (result.error_value().is_framework_error()) {
FX_LOGS(ERROR) << "Unexpected FIDL framework error: " << result.error_value();
} else {
FX_LOGS(INFO) << "WriteItem Error: "
<< fidl::ToUnderlying(result.error_value().domain_error());
}
} else {
FX_LOGS(INFO) << "WriteItem Success";
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// If the `max_export_size` is 0, no export is possible, so just ignore this block. This check
// isn't strictly necessary, but does avoid extra work down the line.
if (conf.max_export_size() > 0) {
// Create a 100Kb VMO to store the resulting export. In a real implementation, we would
// likely receive the VMO representing the to-be-written file from file system like vfs of
// fxfs.
zx::vmo vmo;
if (zx_status_t status = zx::vmo::create(conf.max_export_size(), 0, &vmo); status != ZX_OK) {
FX_PLOGS(ERROR, status) << "Failed to create VMO";
return -1;
}
client->Export({std::move(vmo)})
.ThenExactlyOnce(
[&](fidl::Result<examples_keyvaluestore_supportexports::Store::Export>& result) {
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over, when we return from this callback.
loop.Quit();
if (!result.is_ok()) {
if (result.error_value().is_framework_error()) {
FX_LOGS(ERROR) << "Unexpected FIDL framework error: " << result.error_value();
} else {
FX_LOGS(INFO) << "Export Error: "
<< fidl::ToUnderlying(result.error_value().domain_error());
}
return;
}
FX_LOGS(INFO) << "Export Success";
// Read the exported data (encoded in byte form as persistent FIDL) from the
// returned VMO. In a real implementation, instead of reading the VMO, we would
// merely forward it to some other storage-handling process. Doing this using a VMO,
// rather than FIDL IPC, would save us frivolous reads and writes at each hop.
size_t content_size = 0;
zx::vmo vmo = std::move(result->filled());
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return;
}
std::vector<uint8_t> encoded_bytes;
encoded_bytes.resize(content_size);
if (vmo.read(encoded_bytes.data(), 0, content_size) != ZX_OK) {
return;
}
// Decode the persistent FIDL that was just read from the file.
fit::result exportable =
fidl::Unpersist<examples_keyvaluestore_supportexports::Exportable>(
cpp20::span(encoded_bytes));
if (exportable.is_error()) {
FX_LOGS(ERROR) << "Failed to unpersist: " << exportable.error_value();
return;
}
if (!exportable->items().has_value()) {
FX_LOGS(INFO) << "Expected items to be set";
return;
}
auto& items = exportable->items().value();
// Log some information about the exported data.
FX_LOGS(INFO) << "Printing " << items.size() << " exported entries, which are:";
for (const auto& item : items) {
FX_LOGS(INFO) << " * " << item.key();
}
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <algorithm>
#include <re2/re2.h>
// An implementation of the |Store| protocol.
class StoreImpl final : public fidl::Server<examples_keyvaluestore_supportexports::Store> {
public:
// Bind this implementation to a channel.
StoreImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](StoreImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})) {}
void WriteItem(WriteItemRequest& request, WriteItemCompleter::Sync& completer) override {
FX_LOGS(INFO) << "WriteItem request received";
auto key = request.attempt().key();
auto value = request.attempt().value();
// Validate the key.
if (!RE2::FullMatch(key, "^[A-Za-z]\\w+[A-Za-z0-9]$")) {
FX_LOGS(INFO) << "Write error: INVALID_KEY, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidKey));
}
// Validate the value.
if (value.empty()) {
FX_LOGS(INFO) << "Write error: INVALID_VALUE, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidValue));
}
if (key_value_store_.find(key) != key_value_store_.end()) {
FX_LOGS(INFO) << "Write error: ALREADY_EXISTS, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kAlreadyExists));
}
// Ensure that the value does not already exist in the store.
key_value_store_.insert({key, value});
FX_LOGS(INFO) << "Wrote value at key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(fit::ok());
}
void Export(ExportRequest& request, ExportCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Export request received";
completer.Reply(Export(std::move(request.empty())));
FX_LOGS(INFO) << "Export response sent";
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_keyvaluestore_supportexports::Store> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
using ExportError = ::examples_keyvaluestore_supportexports::ExportError;
using Exportable = ::examples_keyvaluestore_supportexports::Exportable;
using Item = ::examples_keyvaluestore_supportexports::Item;
fit::result<ExportError, zx::vmo> Export(zx::vmo vmo) {
if (key_value_store_.empty()) {
return fit::error(ExportError::kEmpty);
}
Exportable exportable;
std::vector<Item> items;
items.reserve(key_value_store_.size());
for (const auto& [k, v] : key_value_store_) {
items.push_back(Item{{.key = k, .value = v}});
}
std::sort(items.begin(), items.end(),
[](const Item& a, const Item& b) { return a.key() < b.key(); });
exportable.items(std::move(items));
fit::result encoded = fidl::Persist(exportable);
if (encoded.is_error()) {
FX_LOGS(ERROR) << "Failed to encode in persistence convention: " << encoded.error_value();
return fit::error(ExportError::kUnknown);
}
size_t content_size = 0;
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (encoded->size() > content_size) {
return fit::error(ExportError::kStorageTooSmall);
}
if (vmo.set_prop_content_size(encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (vmo.write(encoded->data(), 0, encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
return fit::ok(std::move(vmo));
}
fidl::ServerBindingRef<examples_keyvaluestore_supportexports::Store> binding_;
// The map that serves as the per-connection instance of the key-value store.
std::unordered_map<std::string, std::vector<uint8_t>> key_value_store_ = {};
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to |Store|.
result = outgoing.AddUnmanagedProtocol<examples_keyvaluestore_supportexports::Store>(
[dispatcher](fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
// Create an instance of our StoreImpl that destroys itself when the connection closes.
new StoreImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Store protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++（有线）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/fidl/new/key_value_store/support_exports/cpp_wire/client/config.h>
#include <src/lib/files/file.h>
#include <src/lib/fxl/strings/string_printf.h>
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_keyvaluestore_supportexports::Store>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Store| protocol: "
<< client_end.status_string();
return -1;
}
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& key : conf.write_items()) {
std::string text;
if (!files::ReadFileToString(fxl::StringPrintf("/pkg/data/%s.txt", key.c_str()), &text)) {
FX_LOGS(ERROR) << "It looks like the correct `resource` dependency has not been packaged";
break;
}
auto value = std::vector<uint8_t>(text.begin(), text.end());
client
->WriteItem(
{fidl::StringView::FromExternal(key), fidl::VectorView<uint8_t>::FromExternal(value)})
.ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_keyvaluestore_supportexports::Store::WriteItem>&
result) {
if (!result.ok()) {
FX_LOGS(ERROR) << "Unexpected framework error";
} else if (result->is_error()) {
FX_LOGS(INFO) << "WriteItem Error: " << fidl::ToUnderlying(result->error_value());
} else {
FX_LOGS(INFO) << "WriteItem Success";
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// If the `max_export_size` is 0, no export is possible, so just ignore this block. This check
// isn't strictly necessary, but does avoid extra work down the line.
if (conf.max_export_size() > 0) {
// Create a 100Kb VMO to store the resulting export. In a real implementation, we would
// likely receive the VMO representing the to-be-written file from file system like vfs of
// fxfs.
zx::vmo vmo;
if (zx_status_t status = zx::vmo::create(conf.max_export_size(), 0, &vmo); status != ZX_OK) {
FX_PLOGS(ERROR, status) << "Failed to create VMO";
return -1;
}
client->Export(std::move(vmo))
.ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_keyvaluestore_supportexports::Store::Export>&
result) {
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over, when we return from this callback.
loop.Quit();
if (!result.ok()) {
FX_LOGS(ERROR) << "Unexpected FIDL framework error: " << result.error();
return;
}
if (!result->is_ok()) {
FX_LOGS(INFO) << "Export Error: " << fidl::ToUnderlying(result->error_value());
return;
}
FX_LOGS(INFO) << "Export Success";
// Read the exported data (encoded in byte form as persistent FIDL) from the
// returned VMO. In a real implementation, instead of reading the VMO, we would
// merely forward it to some other storage-handling process. Doing this using a VMO,
// rather than FIDL IPC, would save us frivolous reads and writes at each hop.
size_t content_size = 0;
zx::vmo vmo = std::move(result->value()->filled);
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return;
}
std::vector<uint8_t> encoded_bytes;
encoded_bytes.resize(content_size);
if (vmo.read(encoded_bytes.data(), 0, content_size) != ZX_OK) {
return;
}
// Decode the persistent FIDL that was just read from the file.
fit::result exportable =
fidl::InplaceUnpersist<examples_keyvaluestore_supportexports::wire::Exportable>(
cpp20::span(encoded_bytes));
if (exportable.is_error()) {
FX_LOGS(ERROR) << "Failed to unpersist: " << exportable.error_value();
return;
}
if (!exportable->has_items()) {
FX_LOGS(INFO) << "Expected items to be set";
return;
}
auto& items = exportable->items();
// Log some information about the exported data.
FX_LOGS(INFO) << "Printing " << items.count() << " exported entries, which are:";
for (const auto& item : items) {
FX_LOGS(INFO) << " * " << item.key.get();
}
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.keyvaluestore.supportexports/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <algorithm>
#include <re2/re2.h>
// An implementation of the |Store| protocol.
class StoreImpl final : public fidl::WireServer<examples_keyvaluestore_supportexports::Store> {
public:
// Bind this implementation to a channel.
StoreImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](StoreImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})) {}
void WriteItem(WriteItemRequestView request, WriteItemCompleter::Sync& completer) override {
FX_LOGS(INFO) << "WriteItem request received";
std::string key{request->attempt.key.get()};
std::vector<uint8_t> value{request->attempt.value.begin(), request->attempt.value.end()};
// Validate the key.
if (!RE2::FullMatch(key, "^[A-Za-z]\\w+[A-Za-z0-9]$")) {
FX_LOGS(INFO) << "Write error: INVALID_KEY, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidKey));
}
// Validate the value.
if (value.empty()) {
FX_LOGS(INFO) << "Write error: INVALID_VALUE, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kInvalidValue));
}
if (key_value_store_.find(key) != key_value_store_.end()) {
FX_LOGS(INFO) << "Write error: ALREADY_EXISTS, For key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(
fit::error(examples_keyvaluestore_supportexports::WriteError::kAlreadyExists));
}
// Ensure that the value does not already exist in the store.
key_value_store_.insert({key, value});
FX_LOGS(INFO) << "Wrote value at key: " << key;
FX_LOGS(INFO) << "WriteItem response sent";
return completer.Reply(fit::success());
}
void Export(ExportRequestView request, ExportCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Export request received";
fit::result result = Export(std::move(request->empty));
if (result.is_ok()) {
completer.ReplySuccess(std::move(result.value()));
} else {
completer.ReplyError(result.error_value());
}
FX_LOGS(INFO) << "Export response sent";
}
using ExportError = ::examples_keyvaluestore_supportexports::wire::ExportError;
using Exportable = ::examples_keyvaluestore_supportexports::wire::Exportable;
using Item = ::examples_keyvaluestore_supportexports::wire::Item;
fit::result<ExportError, zx::vmo> Export(zx::vmo vmo) {
if (key_value_store_.empty()) {
return fit::error(ExportError::kEmpty);
}
fidl::Arena arena;
fidl::VectorView<Item> items;
items.Allocate(arena, key_value_store_.size());
size_t count = 0;
for (auto& [k, v] : key_value_store_) {
// Create a wire |Item| object that borrows from |k| and |v|.
// Since |k| and |v| are references into the long living |key_value_store_|,
// while |items| only live within the current function scope,
// this operation is safe.
items[count] = Item{
.key = fidl::StringView::FromExternal(k),
.value = fidl::VectorView<uint8_t>::FromExternal(v),
};
count++;
}
std::sort(items.begin(), items.end(),
[](const Item& a, const Item& b) { return a.key.get() < b.key.get(); });
Exportable exportable = Exportable::Builder(arena).items(items).Build();
fit::result encoded = fidl::Persist(exportable);
if (encoded.is_error()) {
FX_LOGS(ERROR) << "Failed to encode in persistence convention: " << encoded.error_value();
return fit::error(ExportError::kUnknown);
}
size_t content_size = 0;
if (vmo.get_prop_content_size(&content_size) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (encoded->size() > content_size) {
return fit::error(ExportError::kStorageTooSmall);
}
if (vmo.set_prop_content_size(encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
if (vmo.write(encoded->data(), 0, encoded->size()) != ZX_OK) {
return fit::error(ExportError::kUnknown);
}
return fit::ok(std::move(vmo));
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_keyvaluestore_supportexports::Store> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
fidl::ServerBindingRef<examples_keyvaluestore_supportexports::Store> binding_;
// The map that serves as the per-connection instance of the key-value store.
//
// Out-of-line references in wire types are always mutable. Thus the
// |const std::vector<uint8_t>| from the baseline needs to be changed to
// non-const as we're making a vector view pointing to it during |Export|,
// even though in practice the value is never mutated.
std::unordered_map<std::string, std::vector<uint8_t>> key_value_store_ = {};
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to |Store|.
result = outgoing.AddUnmanagedProtocol<examples_keyvaluestore_supportexports::Store>(
[dispatcher](fidl::ServerEnd<examples_keyvaluestore_supportexports::Store> server_end) {
// Create an instance of our StoreImpl that destroys itself when the connection closes.
new StoreImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Store protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
协议结束
FIDL 配方：协议结束
协议端表示通道连接的一个端点，该端点上会读出某些指定的 FIDL 协议。此连接的服务器端是 server_end，而客户端是 client_end。
协议结束具有必需的约束条件，用于指定通过连接说出的 FIDL 协议。例如，client_end:Foo 表示 Zircon 通道的客户端端点，该通道上交换的所有消息都将符合该 FIDL 协议中定义的方法和事件，而 server_end:Foo 表示相反端点。
对键值对存储非常有用的一个操作是按顺序迭代：也就是说，在给定键时，可按顺序返回显示在该键后面的元素列表（通常会分页）。
推理
在 FIDL 中，最好使用迭代器来实现此目的，该迭代器通常作为可以发生此迭代的单独协议来实现。使用单独的协议因此使用单独的通道有许多好处，包括消除通过主协议执行的其他操作中的迭代拉取请求。
协议 P 的通道连接的客户端和服务器端可以分别表示为 FIDL 数据类型，分别表示为 client_end:P 和 server_end:P。这些类型统称为协议端，表示将 FIDL 客户端连接到其相应服务器的另一种（非 @discoverable）方式：通过现有的 FIDL 连接！
协议结尾是一般 FIDL 概念（即资源类型）的特定实例。资源类型包含 FIDL 句柄，因此需要对类型的使用方式做出额外限制。类型必须始终是唯一的，因为底层资源由其他 capability 管理器（通常是 Zircon 内核）进行中介。在不涉及管理器的情况下，通过简单的内存中复制来复制此类资源是不可能的。为防止此类重复，FIDL 中的所有资源类型始终都是只能移动的资源类型。
最后，Iterator 协议本身的 Get() 方法对返回载荷使用大小限制。这限制了在单次拉取中可能传输的数据量，让您可以在一定程度上控制资源使用。这还会创建自然的分页边界：服务器只需一次准备小批量，而不是一次性生成所有结果的巨型转储。
实现
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.additerator;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value vector<byte>:64000;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to create an iterator.
type IterateConnectionError = flexible enum {
/// The starting key was not found.
UNKNOWN_START_AT = 1;
};
/// A key-value store which supports insertion and iteration.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Iterates over the items in the store, using lexicographic ordering over the keys.
///
/// The [`iterator`] is [pipelined][pipelining] to the server, such that the client can
/// immediately send requests over the new connection.
///
/// [pipelining]: https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#request-pipelining
flexible Iterate(resource struct {
/// If present, requests to start the iteration at this item.
starting_at string:<128, optional>;
/// The [`Iterator`] server endpoint. The client creates both ends of the channel and
/// retains the `client_end` locally to use for pulling iteration pages, while sending the
/// `server_end` off to be fulfilled by the server.
iterator server_end:Iterator;
}) -> () error IterateConnectionError;
};
/// An iterator for the key-value store. Note that this protocol makes no guarantee of atomicity -
/// the values may change between pulls from the iterator. Unlike the `Store` protocol above, this
/// protocol is not `@discoverable`: it is not independently published by the component that
/// implements it, but rather must have one of its two protocol ends transmitted over an existing
/// FIDL connection.
///
/// As is often the case with iterators, the client indicates that they are done with an instance of
/// the iterator by simply closing their end of the connection.
///
/// Since the iterator is associated only with the Iterate method, it is declared as closed rather
/// than open. This is because changes to how iteration works are more likely to require replacing
/// the Iterate method completely (which is fine because that method is flexible) rather than
/// evolving the Iterator protocol.
closed protocol Iterator {
/// Gets the next batch of keys.
///
/// The client pulls keys rather than having the server proactively push them, to implement
/// [flow control][flow-control] over the messages.
///
/// [flow-control]:
/// https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#prefer_pull_to_push
strict Get() -> (struct {
/// A list of keys. If the iterator has reached the end of iteration, the list will be
/// empty. The client is expected to then close the connection.
entries vector<string:128>:10;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A key to iterate from, after all items in `write_items` have been written.
iterate_from: {
type: "string",
max_size: 64,
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
use {
fidl::endpoints::create_proxy,
fidl_examples_keyvaluestore_additerator::{Item, IteratorMarker, StoreMarker},
futures::join,
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
if !config.iterate_from.is_empty() {
// This helper creates a channel, and returns two protocol ends: the `client_end` is already
// conveniently bound to the correct FIDL protocol, `Iterator`, while the `server_end` is
// unbound and ready to be sent over the wire.
let (iterator, server_end) = create_proxy::<IteratorMarker>()?;
// There is no need to wait for the iterator to connect before sending the first `Get()`
// request - since we already hold the `client_end` of the connection, we can start queuing
// requests on it immediately.
let connect_to_iterator = store.iterate(Some(config.iterate_from.as_str()), server_end);
let first_get = iterator.get();
// Wait until both the connection and the first request resolve - an error in either case
// triggers an immediate resolution of the combined future.
let (connection, first_page) = join!(connect_to_iterator, first_get);
// Handle any connection error. If this has occurred, it is impossible for the first `Get()`
// call to have resolved successfully, so check this error first.
if let Err(err) = connection.context("Could not connect to Iterator")? {
println!("Iterator Connection Error: {}", err.into_primitive());
} else {
println!("Iterator Connection Success");
// Consecutively repeat the `Get()` request if the previous response was not empty.
let mut entries = first_page.context("Could not get page from Iterator")?;
while !&entries.is_empty() {
for entry in entries.iter() {
println!("Iterator Entry: {}", entry);
}
entries = iterator.get().await.context("Could not get page from Iterator")?;
}
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
};
use {
fidl_examples_keyvaluestore_additerator::{
Item, IterateConnectionError, IteratorRequest, IteratorRequestStream, StoreRequest,
StoreRequestStream, WriteError,
},
fuchsia_async as fasync,
std::collections::btree_map::Entry,
std::collections::BTreeMap,
std::ops::Bound::*,
std::sync::Arc,
std::sync::Mutex,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut BTreeMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Handler for the `Iterate` method, which deals with validating that the requested start position
/// exists, and then sets up the asynchronous side channel for the actual iteration to occur over.
fn iterate(
store: Arc<Mutex<BTreeMap<String, Vec<u8>>>>,
starting_at: Option<String>,
stream: IteratorRequestStream,
) -> Result<(), IterateConnectionError> {
// Validate that the starting key, if supplied, actually exists.
if let Some(start_key) = starting_at.clone() {
if !store.lock().unwrap().contains_key(&start_key) {
return Err(IterateConnectionError::UnknownStartAt);
}
}
// Spawn a detached task. This allows the method call to return while the iteration continues in
// a separate, unawaited task.
fasync::Task::spawn(async move {
// Serve the iteration requests. Note that access to the underlying store is behind a
// contended `Mutex`, meaning that the iteration is not atomic: page contents could shift,
// change, or disappear entirely between `Get()` requests.
stream
.map(|result| result.context("failed request"))
.try_fold(
match starting_at {
Some(start_key) => Included(start_key),
None => Unbounded,
},
|mut lower_bound, request| async {
match request {
IteratorRequest::Get { responder } => {
println!("Iterator page request received");
// The `page_size` should be kept in sync with the size constraint on
// the iterator's response, as defined in the FIDL protocol.
static PAGE_SIZE: usize = 10;
// An iterator, beginning at `lower_bound` and tracking the pagination's
// progress through iteration as each page is pulled by a client-sent
// `Get()` request.
let held_store = store.lock().unwrap();
let mut entries = held_store.range((lower_bound.clone(), Unbounded));
let mut current_page = vec![];
for _ in 0..PAGE_SIZE {
match entries.next() {
Some(entry) => {
current_page.push(entry.0.clone());
}
None => break,
}
}
// Update the `lower_bound` - either inclusive of the next item in the
// iteration, or exclusive of the last seen item if the iteration has
// finished. This `lower_bound` will be passed to the next request
// handler as its starting point.
lower_bound = match entries.next() {
Some(next) => Included(next.0.clone()),
None => match current_page.last() {
Some(tail) => Excluded(tail.clone()),
None => lower_bound,
},
};
// Send the page. At the end of this scope, the `held_store` lock gets
// dropped, and therefore released.
responder.send(¤t_page).context("error sending reply")?;
println!("Iterator page sent");
}
}
Ok(lower_bound)
},
)
.await
.ok();
})
.detach();
Ok(())
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
//
// Note that we now use an `Arc<Mutex<BTreeMap>>`, replacing the previous `RefCell<HashMap>`.
// The `BTreeMap` is used because we want an ordered map, to better facilitate iteration. The
// `Arc<Mutex<...>>` is used because there are now multiple async tasks accessing the: one main
// task which handles communication over the protocol, and one additional task per iterator
// protocol. `Arc<Mutex<...>>` is the simplest way to synchronize concurrent access between
// these racing tasks.
let store = &Arc::new(Mutex::new(BTreeMap::<String, Vec<u8>>::new()));
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.clone().lock().unwrap(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::Iterate { starting_at, iterator, responder } => {
println!("Iterate request received");
// The `iterate` handler does a quick check to see that the request is valid,
// then spins up a separate worker task to serve the newly minted `Iterator`
// protocol instance, allowing this call to return immediately and continue the
// request stream with other work.
responder
.send(iterate(store.clone(), starting_at, iterator.into_stream()?))
.context("error sending reply")?;
println!("Iterate response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
协议
FIDL 配方：协议
协议描述了一组可通过通道发送消息来调用的方法。它描述了客户端和服务器之间可通过哪个接口交换 FIDL 数据。
在此示例中，您将创建一个基本的计算器服务器和客户端，该服务器和客户端显示了首先定义然后传送和使用 FIDL 协议所需的基本设置。
首先，您需要定义接口定义和自动化测试框架。接口定义（.fidl 文件本身）是所有新 FIDL 协议的起点。此外，该计算器包含创建客户端-服务器模式所需的 CML 和领域定义，这些模式可用作任意实现的项目基架。
FIDL 代码如下所示：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// The namespace for this FIDL protocol. This namespace is how both consumers (clients) and providers (servers) reference this protocol.
library examples.calculator.baseline;
// @discoverable indicates 'Calculator' is a protocol that will be served under the examples.calculator.baseline libarary namespace. https://fuchsia.dev/fuchsia-src/reference/fidl/language/attributes#discoverable . If @discoverable is missing, it will lead to a compile time error when trying to import the library.
@discoverable
// A limited-functionality calculator 'protocol' that adds and subtracts integers.
open protocol Calculator {
// Takes as input a struct with two integers, and returns their sum: (a+b)=sum. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Add(struct {
a int32;
b int32;
}) -> (struct {
sum int64;
});
// Takes as input a struct with two integers, and returns their difference: (a-b)=difference. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Subtract(struct {
a int32;
b int32;
}) -> (struct {
difference int64;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
config: {},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
expose: [
{
protocol: "examples.calculator.baseline.Calculator",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.calculator.baseline.Calculator",
from: "#server",
to: "#client",
},
// Route logging support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// TODO(https://fxbug.dev/42063075): Rust implementation.
服务器
// TODO(https://fxbug.dev/42063075): Rust implementation.
C++（自然）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
对于某些开发者（例如平台开发者）来说，从头开始创建 FIDL 协议（如此示例所示）可能是更常见的场景。不过，其他类型的开发者也可以受益于学习如何构造 FIDL 协议（即使他们通常不会这样做）。这有助于您了解 FIDL 的所有要素，包括语法、语法、语言功能、如何提供和使用给定 FIDL 协议，以及构建系统的工作原理。对于后续步骤，此基准后面的示例展示了如何扩展现有的 FIDL 协议，这应该是一种相当常见的做法。
递归类型
FIDL 方案：递归类型
递归类型是指在其定义中以传递方式引用自身的类型。当某个类型直接引用自身时，或者当它引用了以传递方式包含它的某些类型链时，就可能会发生这种情况。例如，在传统的树形数据结构中，每个节点要么仅包含数据（“一叶”），要么仅包含数据和对更多子节点的引用（“分支”）。在后一种情况下，该节点以递归方式包含一个嵌套树定义，并根据需要重复尽可能大的深度。
FIDL 支持递归类型，前提是包含循环中至少有一个链（即引回原始类型的类型定义链）是可选的。如果链中没有任何类型是可选的，则该类型是不可编码的，因为每种类型的每个实例都至少需要其中包含一个类型，即无限多个类型。
在此变体中，我们允许键值对存储区将其他键值对存储区作为成员。简而言之，我们将其变成一棵树。为此，我们将 value 的原始定义替换为使用双成员 union 的定义：一个变体使用与之前相同的 vector<byte> 类型存储叶节点，而另一个变体以其他嵌套存储的形式存储分支节点。
推理
在这里，我们看到可选性的几种用途，我们可以借此声明一个可能存在或可能不存在的类型。FIDL 中有三种可选类型：
- 始终在线在线存储的类型，因此有一种内置方式，通过 null 信封来描述“缺失”。为这些类型启用可选性不会影响包含它们的消息的传输形状，而只是更改该特定类型有效的值。通过添加
:optional约束条件，union、vector<T>、client_end、server_end和zx.Handle类型均可设为可选类型。通过将valueunion设为可选，我们能够采用不存在的value的形式引入规范的“null”条目。这意味着空bytes和缺失/空store属性都是无效值。 - 与上述类型不同，
struct布局没有额外的空间可存储 null 标头。因此，需要将其封装在信封中，从而更改包含它的消息的线上形状。为了确保这种导线修改效果易于辨认，必须将Itemstruct类型封装在box<T>类型模板中。 - 最后，
table布局始终是可选的。如果table不存在，则只是未设置任何成员的标识符。
树是一种天生的自引用数据结构：树中的任何节点都可能包含具有纯数据的叶（在本例中为字符串）或具有更多节点的子树。这需要递归：Item 的定义现在以传递方式依赖于其本身！在 FIDL 中表示递归类型可能有点复杂，尤其是因为目前对支持的内容有些有限。只要自引用创建的周期中至少有一个可选类型，我们就可以支持此类类型。例如，在这里，我们将 items struct 成员定义为 box<Item>，从而打破包含循环。
这些更改还大量使用了匿名类型（即声明内嵌在其单一使用点的类型），而不是被命名的顶级 type 声明。默认情况下，生成的语言绑定中的匿名类型名称取自其本地上下文。例如，新引入的 flexible union 将采用其自有成员的名称 Value，新引入的 struct 将变为 Store，依此类推。由于这种启发式方法有时可能会导致冲突，因此 FIDL 提供了应急方法，允许作者手动替换匿名类型的生成名称。这是通过 @generated_name 属性实现的，该属性可用于更改后端生成的名称。我们可以在这里使用一个示例，将原本的 Store 类型重命名为 NestedStore，以防止名称与使用相同名称的 protocol 声明发生名称冲突。
实现
FIDL、CML 和 Realm 接口定义修改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supporttrees;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value strict union {
// Keep the original `bytes` as one of the options in the new union. All leaf nodes in the
// tree must be `bytes`, or absent unions (representing empty). Empty byte arrays are
// disallowed.
1: bytes vector<byte>:64000;
// Allows a store within a store, thereby turning our flat key-value store into a tree
// thereof. Note the use of `@generated_name` to prevent a type-name collision with the
// `Store` protocol below, and the use of `box<T>` to ensure that there is a break in the
// chain of recursion, thereby allowing `Item` to include itself in its own definition.
//
// This is a table so that added fields, like for example a `hash`, can be easily added in
// the future.
2: store @generated_name("nested_store") table {
1: items vector<box<Item>>;
};
}:optional;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A newline separated list nested entries. The first line should be the key
// for the nested store, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
write_nested: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A list of keys, all of which will be populated as null entries.
write_null: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_supporttrees::{Item, NestedStore, StoreMarker, Value},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
let res = store
.write_item(&Item {
key: key.clone(),
value: Some(Box::new(Value::Bytes(value.into_bytes()))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Add nested entries to the key-value store as well. The entries are strings, where the first
// line is the key of the entry, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
for spec in config.write_nested.into_iter() {
let mut items = vec![];
let mut nested_store = NestedStore::default();
let mut lines = spec.split("\n");
let key = lines.next().unwrap();
// For each entry, make a new entry in the `NestedStore` being built.
for entry in lines {
let path = format!("/pkg/data/{}.txt", entry);
let contents = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
items.push(Some(Box::new(Item {
key: entry.to_string(),
value: Some(Box::new(Value::Bytes(contents.into()))),
})));
}
nested_store.items = Some(items);
// Send the `NestedStore`, represented as a vector of values.
let res = store
.write_item(&Item {
key: key.to_string(),
value: Some(Box::new(Value::Store(nested_store))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Each entry in this list is a null value in the store.
for key in config.write_null.into_iter() {
match store.write_item(&Item { key: key.to_string(), value: None }).await? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_supporttrees::{
Item, StoreRequest, StoreRequestStream, Value, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
std::str::from_utf8,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
// A representation of a key-value store that can contain an arbitrarily deep nesting of other
// key-value stores.
#[allow(dead_code)] // TODO(https://fxbug.dev/318827209)
enum StoreNode {
Leaf(Option<Vec<u8>>),
Branch(Box<HashMap<String, StoreNode>>),
}
/// Recursive item writer, which takes a `StoreNode` that may not necessarily be the root node, and
/// writes an entry to it.
fn write_item(
store: &mut HashMap<String, StoreNode>,
attempt: Item,
path: &str,
) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
let key = format!("{}{}", &path, entry.key());
match attempt.value {
// Null entries are allowed.
None => {
println!("Wrote value: NONE at key: {}", key);
entry.insert(StoreNode::Leaf(None));
}
Some(value) => match *value {
// If this is a nested store, recursively make a new store to insert at this
// position.
Value::Store(entry_list) => {
// Validate the value - absent stores, items lists with no children, or any
// of the elements within that list being empty boxes, are all not allowed.
if entry_list.items.is_some() {
let items = entry_list.items.unwrap();
if !items.is_empty() && items.iter().all(|i| i.is_some()) {
let nested_path = format!("{}/", key);
let mut nested_store = HashMap::<String, StoreNode>::new();
for item in items.into_iter() {
write_item(&mut nested_store, *item.unwrap(), &nested_path)?;
}
println!("Created branch at key: {}", key);
entry.insert(StoreNode::Branch(Box::new(nested_store)));
return Ok(());
}
}
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
// This is a simple leaf node on this branch.
Value::Bytes(value) => {
// Validate the value.
if value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
println!("Wrote key: {}, value: {:?}", key, from_utf8(&value).unwrap());
entry.insert(StoreNode::Leaf(Some(value)));
}
},
}
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, StoreNode>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt, ""))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
资源类型
FIDL 方案：资源类型
FIDL 资源类型是一种旨在传递句柄的类型。由于 FIDL 句柄是对 capability 的唯一引用，因此任何包含一个 FIDL 句柄的类型都会继承此行为：它也无法复制。这样一来，资源便具有感染力：如果值类型变为资源类型，则以传递方式包含它的所有类型也必须这样做。
对键值对存储非常有用的一个操作是按顺序迭代：也就是说，在给定键时，可按顺序返回显示在该键后面的元素列表（通常会分页）。
推理
在 FIDL 中，最好使用迭代器来实现此目的，该迭代器通常作为可以发生此迭代的单独协议来实现。使用单独的协议因此使用单独的通道有许多好处，包括消除通过主协议执行的其他操作中的迭代拉取请求。
协议 P 的通道连接的客户端和服务器端可以分别表示为 FIDL 数据类型，分别表示为 client_end:P 和 server_end:P。这些类型统称为协议端，表示将 FIDL 客户端连接到其相应服务器的另一种（非 @discoverable）方式：通过现有的 FIDL 连接！
协议结尾是一般 FIDL 概念（即资源类型）的特定实例。资源类型包含 FIDL 句柄，因此需要对类型的使用方式做出额外限制。类型必须始终是唯一的，因为底层资源由其他 capability 管理器（通常是 Zircon 内核）进行中介。在不涉及管理器的情况下，通过简单的内存中复制来复制此类资源是不可能的。为防止此类重复，FIDL 中的所有资源类型始终都是只能移动的资源类型。
最后，Iterator 协议本身的 Get() 方法对返回载荷使用大小限制。这限制了在单次拉取中可能传输的数据量，让您可以在一定程度上控制资源使用。这还会创建自然的分页边界：服务器只需一次准备小批量，而不是一次性生成所有结果的巨型转储。
实现
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.additerator;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value vector<byte>:64000;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to create an iterator.
type IterateConnectionError = flexible enum {
/// The starting key was not found.
UNKNOWN_START_AT = 1;
};
/// A key-value store which supports insertion and iteration.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Iterates over the items in the store, using lexicographic ordering over the keys.
///
/// The [`iterator`] is [pipelined][pipelining] to the server, such that the client can
/// immediately send requests over the new connection.
///
/// [pipelining]: https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#request-pipelining
flexible Iterate(resource struct {
/// If present, requests to start the iteration at this item.
starting_at string:<128, optional>;
/// The [`Iterator`] server endpoint. The client creates both ends of the channel and
/// retains the `client_end` locally to use for pulling iteration pages, while sending the
/// `server_end` off to be fulfilled by the server.
iterator server_end:Iterator;
}) -> () error IterateConnectionError;
};
/// An iterator for the key-value store. Note that this protocol makes no guarantee of atomicity -
/// the values may change between pulls from the iterator. Unlike the `Store` protocol above, this
/// protocol is not `@discoverable`: it is not independently published by the component that
/// implements it, but rather must have one of its two protocol ends transmitted over an existing
/// FIDL connection.
///
/// As is often the case with iterators, the client indicates that they are done with an instance of
/// the iterator by simply closing their end of the connection.
///
/// Since the iterator is associated only with the Iterate method, it is declared as closed rather
/// than open. This is because changes to how iteration works are more likely to require replacing
/// the Iterate method completely (which is fine because that method is flexible) rather than
/// evolving the Iterator protocol.
closed protocol Iterator {
/// Gets the next batch of keys.
///
/// The client pulls keys rather than having the server proactively push them, to implement
/// [flow control][flow-control] over the messages.
///
/// [flow-control]:
/// https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#prefer_pull_to_push
strict Get() -> (struct {
/// A list of keys. If the iterator has reached the end of iteration, the list will be
/// empty. The client is expected to then close the connection.
entries vector<string:128>:10;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A key to iterate from, after all items in `write_items` have been written.
iterate_from: {
type: "string",
max_size: 64,
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
use {
fidl::endpoints::create_proxy,
fidl_examples_keyvaluestore_additerator::{Item, IteratorMarker, StoreMarker},
futures::join,
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
if !config.iterate_from.is_empty() {
// This helper creates a channel, and returns two protocol ends: the `client_end` is already
// conveniently bound to the correct FIDL protocol, `Iterator`, while the `server_end` is
// unbound and ready to be sent over the wire.
let (iterator, server_end) = create_proxy::<IteratorMarker>()?;
// There is no need to wait for the iterator to connect before sending the first `Get()`
// request - since we already hold the `client_end` of the connection, we can start queuing
// requests on it immediately.
let connect_to_iterator = store.iterate(Some(config.iterate_from.as_str()), server_end);
let first_get = iterator.get();
// Wait until both the connection and the first request resolve - an error in either case
// triggers an immediate resolution of the combined future.
let (connection, first_page) = join!(connect_to_iterator, first_get);
// Handle any connection error. If this has occurred, it is impossible for the first `Get()`
// call to have resolved successfully, so check this error first.
if let Err(err) = connection.context("Could not connect to Iterator")? {
println!("Iterator Connection Error: {}", err.into_primitive());
} else {
println!("Iterator Connection Success");
// Consecutively repeat the `Get()` request if the previous response was not empty.
let mut entries = first_page.context("Could not get page from Iterator")?;
while !&entries.is_empty() {
for entry in entries.iter() {
println!("Iterator Entry: {}", entry);
}
entries = iterator.get().await.context("Could not get page from Iterator")?;
}
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
};
use {
fidl_examples_keyvaluestore_additerator::{
Item, IterateConnectionError, IteratorRequest, IteratorRequestStream, StoreRequest,
StoreRequestStream, WriteError,
},
fuchsia_async as fasync,
std::collections::btree_map::Entry,
std::collections::BTreeMap,
std::ops::Bound::*,
std::sync::Arc,
std::sync::Mutex,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut BTreeMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Handler for the `Iterate` method, which deals with validating that the requested start position
/// exists, and then sets up the asynchronous side channel for the actual iteration to occur over.
fn iterate(
store: Arc<Mutex<BTreeMap<String, Vec<u8>>>>,
starting_at: Option<String>,
stream: IteratorRequestStream,
) -> Result<(), IterateConnectionError> {
// Validate that the starting key, if supplied, actually exists.
if let Some(start_key) = starting_at.clone() {
if !store.lock().unwrap().contains_key(&start_key) {
return Err(IterateConnectionError::UnknownStartAt);
}
}
// Spawn a detached task. This allows the method call to return while the iteration continues in
// a separate, unawaited task.
fasync::Task::spawn(async move {
// Serve the iteration requests. Note that access to the underlying store is behind a
// contended `Mutex`, meaning that the iteration is not atomic: page contents could shift,
// change, or disappear entirely between `Get()` requests.
stream
.map(|result| result.context("failed request"))
.try_fold(
match starting_at {
Some(start_key) => Included(start_key),
None => Unbounded,
},
|mut lower_bound, request| async {
match request {
IteratorRequest::Get { responder } => {
println!("Iterator page request received");
// The `page_size` should be kept in sync with the size constraint on
// the iterator's response, as defined in the FIDL protocol.
static PAGE_SIZE: usize = 10;
// An iterator, beginning at `lower_bound` and tracking the pagination's
// progress through iteration as each page is pulled by a client-sent
// `Get()` request.
let held_store = store.lock().unwrap();
let mut entries = held_store.range((lower_bound.clone(), Unbounded));
let mut current_page = vec![];
for _ in 0..PAGE_SIZE {
match entries.next() {
Some(entry) => {
current_page.push(entry.0.clone());
}
None => break,
}
}
// Update the `lower_bound` - either inclusive of the next item in the
// iteration, or exclusive of the last seen item if the iteration has
// finished. This `lower_bound` will be passed to the next request
// handler as its starting point.
lower_bound = match entries.next() {
Some(next) => Included(next.0.clone()),
None => match current_page.last() {
Some(tail) => Excluded(tail.clone()),
None => lower_bound,
},
};
// Send the page. At the end of this scope, the `held_store` lock gets
// dropped, and therefore released.
responder.send(¤t_page).context("error sending reply")?;
println!("Iterator page sent");
}
}
Ok(lower_bound)
},
)
.await
.ok();
})
.detach();
Ok(())
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
//
// Note that we now use an `Arc<Mutex<BTreeMap>>`, replacing the previous `RefCell<HashMap>`.
// The `BTreeMap` is used because we want an ordered map, to better facilitate iteration. The
// `Arc<Mutex<...>>` is used because there are now multiple async tasks accessing the: one main
// task which handles communication over the protocol, and one additional task per iterator
// protocol. `Arc<Mutex<...>>` is the simplest way to synchronize concurrent access between
// these racing tasks.
let store = &Arc::new(Mutex::new(BTreeMap::<String, Vec<u8>>::new()));
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.clone().lock().unwrap(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::Iterate { starting_at, iterator, responder } => {
println!("Iterate request received");
// The `iterate` handler does a quick check to see that the request is valid,
// then spins up a separate worker task to serve the newly minted `Iterator`
// protocol instance, allowing this call to return immediately and continue the
// request stream with other work.
responder
.send(iterate(store.clone(), starting_at, iterator.into_stream()?))
.context("error sending reply")?;
println!("Iterate response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
标量类型
FIDL 方案：标量类型
FIDL 的标量类型是一种类型，包含其所有内置基元以及内置非基元 string 类型。
推理
键值对存储基准示例的实现是一个很好的起点，但一个主要缺点是数据存储为原始字节。FIDL 是一种类型丰富的语言。例如，强制将 UTF-8 字符串存储为非类型字节数组的数据，对于 *.fidl 文件的读取器以及使用从该文件生成的绑定的编程人员来说，都会清除这些有价值的类型信息。
实现
这项更改的主要目标是将基准用例的 vector<byte> 类型 value 成员替换为用于存储许多可能类型的 union。事实上，经过此次变更，您可以很好地了解 FIDL 的值类型：
- FIDL 的所有内置标量类型在
Valueunion中用作变体：bool、uint8、uint16、uint32、uint64、int8、int16、int32、int64、float32和float64（也称为 FIDL 的基元类型）以及string。 - 此
union还包含使用 FIDL 的内置array<T, N>和vector<T>类型模板的功能。 - 此示例中使用 FIDL 的所有类型布局（即
bits、enum、table、union和struct）至少一次。
用于 WriteItem 的请求和响应载荷也已分别从 struct 更改为命名的 table 和内嵌的 flexible union。事实上，这三种布局中的任何一种均可用作请求/响应负载。后两者（分别称为表载荷和 *联合载荷）在除消息大小对最敏感的用例之外，是首选。这是因为将来以与二进制文件兼容的方式扩展这些变量会更容易。
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.usegenericvalues;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value Value;
};
// Because the `Value` must be used both in the request and the response, we give it its own named
// type. The type is a `union` of all possible data types that we take as values, and is marked
// `flexible` to allow for the easy addition of new data types in the future.
type Value = flexible union {
// Keep the original `bytes` as one of the options in the new union.
1: bytes vector<byte>:64000;
// A `string` is very similar to `vector<byte>` on the wire, with the extra constraint that
// it enforces that it enforces that the byte vector in question is valid UTF-8.
2: string string:64000;
// All of FIDL's primitive types.
3: bool bool;
4: uint8 uint8;
5: int8 int8;
6: uint16 uint16;
7: int16 int16;
8: uint32 uint32;
9: int32 int32;
10: float32 float32;
11: uint64 uint64;
12: int64 int64;
13: float64 float64;
// FIDL does not natively support 128-bit integer types, so we have to define our own
// representations.
14: uint128 array<uint64, 2>;
};
// Because we now supoprt a richer range of types as values in our store, it is helpful to use a
// `flexible`, and therefore evolvable, `bits` type to store write options.
type WriteOptions = flexible bits : uint8 {
// This flag allows us to overwrite existing data when there is a collision, rather than failing
// with an `WriteError.ALREADY_EXISTS`.
OVERWRITE = 0b1;
// This flag allows us to concatenate to existing data when there is a collision, rather than
// failing with an `WriteError.ALREADY_EXISTS`. "Concatenation" means addition for the numeric
// variants and appending to the `bytes`/`string` variants. If no existing data can be found, we
// "concatenate" to default values of zero and an empty vector, respectively. Attempting to
// concatenate to an existing variant of a different type will return a
// `WriteError.INVALID_VALUE` error.
CONCAT = 0b10;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
///
/// Since the value stored in the key-value store can now be different from the input (if the
/// `WriteOptions.CONCAT` flag is set), we need to return the resulting `Value` to the
/// requester.
///
/// We use an (anonymous) `table` and a (named) `flexible union` as the request and response
/// payload, respectively, to allow for easier future evolution. Both of these types are
/// `flexible`, meaning that adding or removing members is binary-compatible. This makes them
/// much easier to evolve that the `struct` types that were previously used, which cannot be
/// changed after release without breaking ABI.
flexible WriteItem(table {
1: attempt Item;
2: options WriteOptions;
}) -> (Value) error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
config: {
// A vector of values for every easily representible type in our key-value store. For
// brevity's sake, the 8, 16, and 32 bit integer types and booleans are omitted.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use all FIDL constructs directly here. In
// particular, floats and nested types are very difficult to represent, and have been
// excluded from this example for the time being.
set_concat_option: { type: "bool" },
set_overwrite_option: { type: "bool" },
write_bytes: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_strings: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_uint64s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
write_int64s: {
type: "vector",
max_count: 16,
element: { type: "int64" },
},
// Note: due to the limitation of structured config not allowing vectors nested in vectors,
// we only set the lower half of the uint128 for simplicity's sake.
write_uint128s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreMarker, StoreProxy, StoreWriteItemRequest, Value, WriteOptions,
},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
// A helper function to sequentially write a single item to the key-value store and print a log when
// successful.
async fn write_next_item(
store: &StoreProxy,
key: &str,
value: Value,
options: WriteOptions,
) -> Result<(), Error> {
// Create an empty request payload using `::default()`.
let mut req = StoreWriteItemRequest::default();
req.options = Some(options);
// Fill in the `Item` we will be attempting to write.
println!("WriteItem request sent: key: {}, value: {:?}", &key, &value);
req.attempt = Some(Item { key: key.to_string(), value: value });
// Send and async `WriteItem` request to the server.
match store.write_item(&req).await.context("Error sending request")? {
Ok(value) => println!("WriteItem response received: {:?}", &value),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
Ok(())
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// All of our requests will have the same bitflags set. Pull these settings from the config.
let mut options = WriteOptions::empty();
options.set(WriteOptions::OVERWRITE, config.set_overwrite_option);
options.set(WriteOptions::CONCAT, config.set_concat_option);
// The structured config provides one input for most data types that can be stored in the data
// store. Iterate through those inputs in the order we see them in the FIDL file.
//
// Note that FIDL unions are rendered as enums in Rust; for example, the `Value` union has now
// become a `Value` Rust enum, with each member taking exactly one argument.
for value in config.write_bytes.into_iter() {
write_next_item(&store, "bytes", Value::Bytes(value.into()), options).await?;
}
for value in config.write_strings.into_iter() {
write_next_item(&store, "string", Value::String(value), options).await?;
}
for value in config.write_uint64s.into_iter() {
write_next_item(&store, "uint64", Value::Uint64(value), options).await?;
}
for value in config.write_int64s.into_iter() {
write_next_item(&store, "int64", Value::Int64(value), options).await?;
}
for value in config.write_uint128s.into_iter() {
write_next_item(&store, "uint128", Value::Uint128([0, value]), options).await?;
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
use {
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreRequest, StoreRequestStream, Value, WriteError, WriteOptions,
},
std::collections::hash_map::OccupiedEntry,
std::ops::Add,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Sums any numeric type.
fn sum<T: Add + Add<Output = T> + Copy>(operands: [T; 2]) -> T {
operands[0] + operands[1]
}
/// Clones and inserts an entry, so that the original (now concatenated) copy may be returned in the
/// response.
fn write(inserting: Value, mut entry: OccupiedEntry<'_, String, Value>) -> Value {
entry.insert(inserting.clone());
println!("Wrote key: {}, value: {:?}", entry.key(), &inserting);
inserting
}
/// Handler for the `WriteItem` method.
fn write_item(
store: &mut HashMap<String, Value>,
attempt: Item,
options: &WriteOptions,
) -> Result<Value, WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY for key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
// The `CONCAT` flag supersedes the `OVERWRITE` flag, so check it first.
if options.contains(WriteOptions::CONCAT) {
match entry.get() {
Value::Bytes(old) => {
if let Value::Bytes(new) = attempt.value {
let mut combined = old.clone();
combined.extend(new);
return Ok(write(Value::Bytes(combined), entry));
}
}
Value::String(old) => {
if let Value::String(new) = attempt.value {
return Ok(write(Value::String(format!("{}{}", old, &new)), entry));
}
}
Value::Uint64(old) => {
if let Value::Uint64(new) = attempt.value {
return Ok(write(Value::Uint64(sum([*old, new])), entry));
}
}
Value::Int64(old) => {
if let Value::Int64(new) = attempt.value {
return Ok(write(Value::Int64(sum([*old, new])), entry));
}
}
// Note: only works on the uint64 range in practice.
Value::Uint128(old) => {
if let Value::Uint128(new) = attempt.value {
return Ok(write(Value::Uint128([0, sum([old[1], new[1]])]), entry));
}
}
_ => {
panic!("actively unsupported type!")
}
}
// Only reachable if the type of the would be concatenated value did not match the
// value already occupying this entry.
println!("Write error: INVALID_VALUE for key: {}", entry.key());
return Err(WriteError::InvalidValue);
}
// If we're not doing CONCAT, check for OVERWRITE next.
if options.contains(WriteOptions::OVERWRITE) {
return Ok(write(attempt.value, entry));
}
println!("Write error: ALREADY_EXISTS for key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote key: {}, value: {:?}", entry.key(), &attempt.value);
entry.insert(attempt.value.clone());
Ok(attempt.value)
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Value>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
// Because we are using a table payload, there is an extra level of indirection. The
// top-level container for the table itself is always called "payload".
StoreRequest::WriteItem { payload, responder } => {
println!("WriteItem request received");
// Error out if either of the request table's members are not set.
let attempt = payload.attempt.context("required field 'attempt' is unset")?;
let options = payload.options.context("required field 'options' is unset")?;
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(
write_item(&mut store.borrow_mut(), attempt, &options)
.as_ref()
.map_err(|e| *e),
)
.context("error sending reply")?;
println!("WriteItem response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
尺寸限制
FIDL 方案：大小限制
FIDL 矢量和字符串可能带有大小限制，用于指定相应类型可以包含的成员数量的限制。对于向量来说，它指的是向量中存储的元素数，而对于字符串来说，它是指字符串包含的字节数。
我们强烈建议使用大小限制，因为它会设置无限大类型的上限。
对键值对存储非常有用的一个操作是按顺序迭代：也就是说，在给定键时，可按顺序返回显示在该键后面的元素列表（通常会分页）。
推理
在 FIDL 中，最好使用迭代器来实现此目的，该迭代器通常作为可以发生此迭代的单独协议来实现。使用单独的协议因此使用单独的通道有许多好处，包括消除通过主协议执行的其他操作中的迭代拉取请求。
协议 P 的通道连接的客户端和服务器端可以分别表示为 FIDL 数据类型，分别表示为 client_end:P 和 server_end:P。这些类型统称为协议端，表示将 FIDL 客户端连接到其相应服务器的另一种（非 @discoverable）方式：通过现有的 FIDL 连接！
协议结尾是一般 FIDL 概念（即资源类型）的特定实例。资源类型包含 FIDL 句柄，因此需要对类型的使用方式做出额外限制。类型必须始终是唯一的，因为底层资源由其他 capability 管理器（通常是 Zircon 内核）进行中介。在不涉及管理器的情况下，通过简单的内存中复制来复制此类资源是不可能的。为防止此类重复，FIDL 中的所有资源类型始终都是只能移动的资源类型。
最后，Iterator 协议本身的 Get() 方法对返回载荷使用大小限制。这限制了在单次拉取中可能传输的数据量，让您可以在一定程度上控制资源使用。这还会创建自然的分页边界：服务器只需一次准备小批量，而不是一次性生成所有结果的巨型转储。
实现
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.additerator;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value vector<byte>:64000;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// An enumeration of things that may go wrong when trying to create an iterator.
type IterateConnectionError = flexible enum {
/// The starting key was not found.
UNKNOWN_START_AT = 1;
};
/// A key-value store which supports insertion and iteration.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
/// Iterates over the items in the store, using lexicographic ordering over the keys.
///
/// The [`iterator`] is [pipelined][pipelining] to the server, such that the client can
/// immediately send requests over the new connection.
///
/// [pipelining]: https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#request-pipelining
flexible Iterate(resource struct {
/// If present, requests to start the iteration at this item.
starting_at string:<128, optional>;
/// The [`Iterator`] server endpoint. The client creates both ends of the channel and
/// retains the `client_end` locally to use for pulling iteration pages, while sending the
/// `server_end` off to be fulfilled by the server.
iterator server_end:Iterator;
}) -> () error IterateConnectionError;
};
/// An iterator for the key-value store. Note that this protocol makes no guarantee of atomicity -
/// the values may change between pulls from the iterator. Unlike the `Store` protocol above, this
/// protocol is not `@discoverable`: it is not independently published by the component that
/// implements it, but rather must have one of its two protocol ends transmitted over an existing
/// FIDL connection.
///
/// As is often the case with iterators, the client indicates that they are done with an instance of
/// the iterator by simply closing their end of the connection.
///
/// Since the iterator is associated only with the Iterate method, it is declared as closed rather
/// than open. This is because changes to how iteration works are more likely to require replacing
/// the Iterate method completely (which is fine because that method is flexible) rather than
/// evolving the Iterator protocol.
closed protocol Iterator {
/// Gets the next batch of keys.
///
/// The client pulls keys rather than having the server proactively push them, to implement
/// [flow control][flow-control] over the messages.
///
/// [flow-control]:
/// https://fuchsia.dev/fuchsia-src/development/api/fidl?hl=en#prefer_pull_to_push
strict Get() -> (struct {
/// A list of keys. If the iterator has reached the end of iteration, the list will be
/// empty. The client is expected to then close the connection.
entries vector<string:128>:10;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A key to iterate from, after all items in `write_items` have been written.
iterate_from: {
type: "string",
max_size: 64,
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.additerator.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.additerator.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
use {
fidl::endpoints::create_proxy,
fidl_examples_keyvaluestore_additerator::{Item, IteratorMarker, StoreMarker},
futures::join,
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
match store.write_item(&Item { key: key, value: value.into_bytes() }).await? {
Ok(_) => println!("WriteItem Success"),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
if !config.iterate_from.is_empty() {
// This helper creates a channel, and returns two protocol ends: the `client_end` is already
// conveniently bound to the correct FIDL protocol, `Iterator`, while the `server_end` is
// unbound and ready to be sent over the wire.
let (iterator, server_end) = create_proxy::<IteratorMarker>()?;
// There is no need to wait for the iterator to connect before sending the first `Get()`
// request - since we already hold the `client_end` of the connection, we can start queuing
// requests on it immediately.
let connect_to_iterator = store.iterate(Some(config.iterate_from.as_str()), server_end);
let first_get = iterator.get();
// Wait until both the connection and the first request resolve - an error in either case
// triggers an immediate resolution of the combined future.
let (connection, first_page) = join!(connect_to_iterator, first_get);
// Handle any connection error. If this has occurred, it is impossible for the first `Get()`
// call to have resolved successfully, so check this error first.
if let Err(err) = connection.context("Could not connect to Iterator")? {
println!("Iterator Connection Error: {}", err.into_primitive());
} else {
println!("Iterator Connection Success");
// Consecutively repeat the `Get()` request if the previous response was not empty.
let mut entries = first_page.context("Could not get page from Iterator")?;
while !&entries.is_empty() {
for entry in entries.iter() {
println!("Iterator Entry: {}", entry);
}
entries = iterator.get().await.context("Could not get page from Iterator")?;
}
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
};
use {
fidl_examples_keyvaluestore_additerator::{
Item, IterateConnectionError, IteratorRequest, IteratorRequestStream, StoreRequest,
StoreRequestStream, WriteError,
},
fuchsia_async as fasync,
std::collections::btree_map::Entry,
std::collections::BTreeMap,
std::ops::Bound::*,
std::sync::Arc,
std::sync::Mutex,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Handler for the `WriteItem` method.
fn write_item(store: &mut BTreeMap<String, Vec<u8>>, attempt: Item) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Validate the value.
if attempt.value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", attempt.key);
return Err(WriteError::InvalidValue);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote value at key: {}", entry.key());
entry.insert(attempt.value);
Ok(())
}
}
}
/// Handler for the `Iterate` method, which deals with validating that the requested start position
/// exists, and then sets up the asynchronous side channel for the actual iteration to occur over.
fn iterate(
store: Arc<Mutex<BTreeMap<String, Vec<u8>>>>,
starting_at: Option<String>,
stream: IteratorRequestStream,
) -> Result<(), IterateConnectionError> {
// Validate that the starting key, if supplied, actually exists.
if let Some(start_key) = starting_at.clone() {
if !store.lock().unwrap().contains_key(&start_key) {
return Err(IterateConnectionError::UnknownStartAt);
}
}
// Spawn a detached task. This allows the method call to return while the iteration continues in
// a separate, unawaited task.
fasync::Task::spawn(async move {
// Serve the iteration requests. Note that access to the underlying store is behind a
// contended `Mutex`, meaning that the iteration is not atomic: page contents could shift,
// change, or disappear entirely between `Get()` requests.
stream
.map(|result| result.context("failed request"))
.try_fold(
match starting_at {
Some(start_key) => Included(start_key),
None => Unbounded,
},
|mut lower_bound, request| async {
match request {
IteratorRequest::Get { responder } => {
println!("Iterator page request received");
// The `page_size` should be kept in sync with the size constraint on
// the iterator's response, as defined in the FIDL protocol.
static PAGE_SIZE: usize = 10;
// An iterator, beginning at `lower_bound` and tracking the pagination's
// progress through iteration as each page is pulled by a client-sent
// `Get()` request.
let held_store = store.lock().unwrap();
let mut entries = held_store.range((lower_bound.clone(), Unbounded));
let mut current_page = vec![];
for _ in 0..PAGE_SIZE {
match entries.next() {
Some(entry) => {
current_page.push(entry.0.clone());
}
None => break,
}
}
// Update the `lower_bound` - either inclusive of the next item in the
// iteration, or exclusive of the last seen item if the iteration has
// finished. This `lower_bound` will be passed to the next request
// handler as its starting point.
lower_bound = match entries.next() {
Some(next) => Included(next.0.clone()),
None => match current_page.last() {
Some(tail) => Excluded(tail.clone()),
None => lower_bound,
},
};
// Send the page. At the end of this scope, the `held_store` lock gets
// dropped, and therefore released.
responder.send(¤t_page).context("error sending reply")?;
println!("Iterator page sent");
}
}
Ok(lower_bound)
},
)
.await
.ok();
})
.detach();
Ok(())
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
//
// Note that we now use an `Arc<Mutex<BTreeMap>>`, replacing the previous `RefCell<HashMap>`.
// The `BTreeMap` is used because we want an ordered map, to better facilitate iteration. The
// `Arc<Mutex<...>>` is used because there are now multiple async tasks accessing the: one main
// task which handles communication over the protocol, and one additional task per iterator
// protocol. `Arc<Mutex<...>>` is the simplest way to synchronize concurrent access between
// these racing tasks.
let store = &Arc::new(Mutex::new(BTreeMap::<String, Vec<u8>>::new()));
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.clone().lock().unwrap(), attempt))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::Iterate { starting_at, iterator, responder } => {
println!("Iterate request received");
// The `iterate` handler does a quick check to see that the request is valid,
// then spins up a separate worker task to serve the newly minted `Iterator`
// protocol instance, allowing this call to return immediately and continue the
// request stream with other work.
responder
.send(iterate(store.clone(), starting_at, iterator.into_stream()?))
.context("error sending reply")?;
println!("Iterate response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
结构载荷
FIDL 方案：结构载荷
结构体载荷是使用 struct 布局的 FIDL 方法载荷。struct 是一个简单的类型化字段序列，类似于 C 结构体的工作原理。
在此示例中，您将创建一个基本的计算器服务器和客户端，该服务器和客户端显示了首先定义然后传送和使用 FIDL 协议所需的基本设置。
首先，您需要定义接口定义和自动化测试框架。接口定义（.fidl 文件本身）是所有新 FIDL 协议的起点。此外，该计算器包含创建客户端-服务器模式所需的 CML 和领域定义，这些模式可用作任意实现的项目基架。
FIDL 代码如下所示：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// The namespace for this FIDL protocol. This namespace is how both consumers (clients) and providers (servers) reference this protocol.
library examples.calculator.baseline;
// @discoverable indicates 'Calculator' is a protocol that will be served under the examples.calculator.baseline libarary namespace. https://fuchsia.dev/fuchsia-src/reference/fidl/language/attributes#discoverable . If @discoverable is missing, it will lead to a compile time error when trying to import the library.
@discoverable
// A limited-functionality calculator 'protocol' that adds and subtracts integers.
open protocol Calculator {
// Takes as input a struct with two integers, and returns their sum: (a+b)=sum. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Add(struct {
a int32;
b int32;
}) -> (struct {
sum int64;
});
// Takes as input a struct with two integers, and returns their difference: (a-b)=difference. This method is infallible (no errors can be generated) as two int32's cannot overflow a result type of int64.
flexible Subtract(struct {
a int32;
b int32;
}) -> (struct {
difference int64;
});
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
config: {},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.calculator.baseline.Calculator" },
],
expose: [
{
protocol: "examples.calculator.baseline.Calculator",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.calculator.baseline.Calculator",
from: "#server",
to: "#client",
},
// Route logging support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// TODO(https://fxbug.dev/42063075): Rust implementation.
服务器
// TODO(https://fxbug.dev/42063075): Rust implementation.
C++（自然）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42063075): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42063075): HLCPP implementation.
对于某些开发者（例如平台开发者）来说，从头开始创建 FIDL 协议（如此示例所示）可能是更常见的场景。不过，其他类型的开发者也可以受益于学习如何构造 FIDL 协议（即使他们通常不会这样做）。这有助于您了解 FIDL 的所有要素，包括语法、语法、语言功能、如何提供和使用给定 FIDL 协议，以及构建系统的工作原理。对于后续步骤，此基准后面的示例展示了如何扩展现有的 FIDL 协议，这应该是一种相当常见的做法。
表载荷
FIDL 方案：表载荷
表载荷是使用 table 布局的 FIDL 方法载荷。用作方法载荷的顶级类型必须使用 struct、table 或 union 之一作为其布局。值得注意的是，一些生成的绑定会“扁平化”传递给 struct 方法载荷的参数，以便每个成员本身在调用签名中被视为函数参数。使用 table 或 union 的载荷永远不会执行该操作，并且始终会传递一个名为 payload 的参数。
推理
键值对存储基准示例的实现是一个很好的起点，但一个主要缺点是数据存储为原始字节。FIDL 是一种类型丰富的语言。例如，强制将 UTF-8 字符串存储为非类型字节数组的数据，对于 *.fidl 文件的读取器以及使用从该文件生成的绑定的编程人员来说，都会清除这些有价值的类型信息。
实现
这项更改的主要目标是将基准用例的 vector<byte> 类型 value 成员替换为用于存储许多可能类型的 union。事实上，经过此次变更，您可以很好地了解 FIDL 的值类型：
- FIDL 的所有内置标量类型在
Valueunion中用作变体：bool、uint8、uint16、uint32、uint64、int8、int16、int32、int64、float32和float64（也称为 FIDL 的基元类型）以及string。 - 此
union还包含使用 FIDL 的内置array<T, N>和vector<T>类型模板的功能。 - 此示例中使用 FIDL 的所有类型布局（即
bits、enum、table、union和struct）至少一次。
用于 WriteItem 的请求和响应载荷也已分别从 struct 更改为命名的 table 和内嵌的 flexible union。事实上，这三种布局中的任何一种均可用作请求/响应负载。后两者（分别称为表载荷和 *联合载荷）在除消息大小对最敏感的用例之外，是首选。这是因为将来以与二进制文件兼容的方式扩展这些变量会更容易。
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.usegenericvalues;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value Value;
};
// Because the `Value` must be used both in the request and the response, we give it its own named
// type. The type is a `union` of all possible data types that we take as values, and is marked
// `flexible` to allow for the easy addition of new data types in the future.
type Value = flexible union {
// Keep the original `bytes` as one of the options in the new union.
1: bytes vector<byte>:64000;
// A `string` is very similar to `vector<byte>` on the wire, with the extra constraint that
// it enforces that it enforces that the byte vector in question is valid UTF-8.
2: string string:64000;
// All of FIDL's primitive types.
3: bool bool;
4: uint8 uint8;
5: int8 int8;
6: uint16 uint16;
7: int16 int16;
8: uint32 uint32;
9: int32 int32;
10: float32 float32;
11: uint64 uint64;
12: int64 int64;
13: float64 float64;
// FIDL does not natively support 128-bit integer types, so we have to define our own
// representations.
14: uint128 array<uint64, 2>;
};
// Because we now supoprt a richer range of types as values in our store, it is helpful to use a
// `flexible`, and therefore evolvable, `bits` type to store write options.
type WriteOptions = flexible bits : uint8 {
// This flag allows us to overwrite existing data when there is a collision, rather than failing
// with an `WriteError.ALREADY_EXISTS`.
OVERWRITE = 0b1;
// This flag allows us to concatenate to existing data when there is a collision, rather than
// failing with an `WriteError.ALREADY_EXISTS`. "Concatenation" means addition for the numeric
// variants and appending to the `bytes`/`string` variants. If no existing data can be found, we
// "concatenate" to default values of zero and an empty vector, respectively. Attempting to
// concatenate to an existing variant of a different type will return a
// `WriteError.INVALID_VALUE` error.
CONCAT = 0b10;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
///
/// Since the value stored in the key-value store can now be different from the input (if the
/// `WriteOptions.CONCAT` flag is set), we need to return the resulting `Value` to the
/// requester.
///
/// We use an (anonymous) `table` and a (named) `flexible union` as the request and response
/// payload, respectively, to allow for easier future evolution. Both of these types are
/// `flexible`, meaning that adding or removing members is binary-compatible. This makes them
/// much easier to evolve that the `struct` types that were previously used, which cannot be
/// changed after release without breaking ABI.
flexible WriteItem(table {
1: attempt Item;
2: options WriteOptions;
}) -> (Value) error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
config: {
// A vector of values for every easily representible type in our key-value store. For
// brevity's sake, the 8, 16, and 32 bit integer types and booleans are omitted.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use all FIDL constructs directly here. In
// particular, floats and nested types are very difficult to represent, and have been
// excluded from this example for the time being.
set_concat_option: { type: "bool" },
set_overwrite_option: { type: "bool" },
write_bytes: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_strings: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_uint64s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
write_int64s: {
type: "vector",
max_count: 16,
element: { type: "int64" },
},
// Note: due to the limitation of structured config not allowing vectors nested in vectors,
// we only set the lower half of the uint128 for simplicity's sake.
write_uint128s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreMarker, StoreProxy, StoreWriteItemRequest, Value, WriteOptions,
},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
// A helper function to sequentially write a single item to the key-value store and print a log when
// successful.
async fn write_next_item(
store: &StoreProxy,
key: &str,
value: Value,
options: WriteOptions,
) -> Result<(), Error> {
// Create an empty request payload using `::default()`.
let mut req = StoreWriteItemRequest::default();
req.options = Some(options);
// Fill in the `Item` we will be attempting to write.
println!("WriteItem request sent: key: {}, value: {:?}", &key, &value);
req.attempt = Some(Item { key: key.to_string(), value: value });
// Send and async `WriteItem` request to the server.
match store.write_item(&req).await.context("Error sending request")? {
Ok(value) => println!("WriteItem response received: {:?}", &value),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
Ok(())
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// All of our requests will have the same bitflags set. Pull these settings from the config.
let mut options = WriteOptions::empty();
options.set(WriteOptions::OVERWRITE, config.set_overwrite_option);
options.set(WriteOptions::CONCAT, config.set_concat_option);
// The structured config provides one input for most data types that can be stored in the data
// store. Iterate through those inputs in the order we see them in the FIDL file.
//
// Note that FIDL unions are rendered as enums in Rust; for example, the `Value` union has now
// become a `Value` Rust enum, with each member taking exactly one argument.
for value in config.write_bytes.into_iter() {
write_next_item(&store, "bytes", Value::Bytes(value.into()), options).await?;
}
for value in config.write_strings.into_iter() {
write_next_item(&store, "string", Value::String(value), options).await?;
}
for value in config.write_uint64s.into_iter() {
write_next_item(&store, "uint64", Value::Uint64(value), options).await?;
}
for value in config.write_int64s.into_iter() {
write_next_item(&store, "int64", Value::Int64(value), options).await?;
}
for value in config.write_uint128s.into_iter() {
write_next_item(&store, "uint128", Value::Uint128([0, value]), options).await?;
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
use {
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreRequest, StoreRequestStream, Value, WriteError, WriteOptions,
},
std::collections::hash_map::OccupiedEntry,
std::ops::Add,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Sums any numeric type.
fn sum<T: Add + Add<Output = T> + Copy>(operands: [T; 2]) -> T {
operands[0] + operands[1]
}
/// Clones and inserts an entry, so that the original (now concatenated) copy may be returned in the
/// response.
fn write(inserting: Value, mut entry: OccupiedEntry<'_, String, Value>) -> Value {
entry.insert(inserting.clone());
println!("Wrote key: {}, value: {:?}", entry.key(), &inserting);
inserting
}
/// Handler for the `WriteItem` method.
fn write_item(
store: &mut HashMap<String, Value>,
attempt: Item,
options: &WriteOptions,
) -> Result<Value, WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY for key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
// The `CONCAT` flag supersedes the `OVERWRITE` flag, so check it first.
if options.contains(WriteOptions::CONCAT) {
match entry.get() {
Value::Bytes(old) => {
if let Value::Bytes(new) = attempt.value {
let mut combined = old.clone();
combined.extend(new);
return Ok(write(Value::Bytes(combined), entry));
}
}
Value::String(old) => {
if let Value::String(new) = attempt.value {
return Ok(write(Value::String(format!("{}{}", old, &new)), entry));
}
}
Value::Uint64(old) => {
if let Value::Uint64(new) = attempt.value {
return Ok(write(Value::Uint64(sum([*old, new])), entry));
}
}
Value::Int64(old) => {
if let Value::Int64(new) = attempt.value {
return Ok(write(Value::Int64(sum([*old, new])), entry));
}
}
// Note: only works on the uint64 range in practice.
Value::Uint128(old) => {
if let Value::Uint128(new) = attempt.value {
return Ok(write(Value::Uint128([0, sum([old[1], new[1]])]), entry));
}
}
_ => {
panic!("actively unsupported type!")
}
}
// Only reachable if the type of the would be concatenated value did not match the
// value already occupying this entry.
println!("Write error: INVALID_VALUE for key: {}", entry.key());
return Err(WriteError::InvalidValue);
}
// If we're not doing CONCAT, check for OVERWRITE next.
if options.contains(WriteOptions::OVERWRITE) {
return Ok(write(attempt.value, entry));
}
println!("Write error: ALREADY_EXISTS for key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote key: {}, value: {:?}", entry.key(), &attempt.value);
entry.insert(attempt.value.clone());
Ok(attempt.value)
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Value>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
// Because we are using a table payload, there is an extra level of indirection. The
// top-level container for the table itself is always called "payload".
StoreRequest::WriteItem { payload, responder } => {
println!("WriteItem request received");
// Error out if either of the request table's members are not set.
let attempt = payload.attempt.context("required field 'attempt' is unset")?;
let options = payload.options.context("required field 'options' is unset")?;
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(
write_item(&mut store.borrow_mut(), attempt, &options)
.as_ref()
.map_err(|e| *e),
)
.context("error sending reply")?;
println!("WriteItem response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
受限事件模式
FIDL 配方：节流事件模式
事件是从服务器发起的 FIDL 调用。由于这些调用没有内置客户端响应，因此不受流控制：服务器可能会将大量此类调用加入队列，并对客户端进行泛洪处理。此问题的一种解决方案是节流事件模式。这种模式涉及添加一个名为 FIDL 方法的客户端，作为一个或多个要同步到的事件的确认点。
服务器在收到客户端的下一个确认调用之前，应该避免发送更多受限事件（此处的确切语义特定于实现协议）。同样，如果服务器在确认服务器前发送的受限事件数超出允许的数量，则客户端应关闭连接。这些限制并未内置于 FIDL 运行时中，并且需要客户端/服务器实现者进行一些手动实现，以确保行为正确。
提升 Instance 协议性能的一种方法是允许批量调用行：我们可以将多行批量调用为一次新的 AddLines(...); 调用，而不是每次要在画布中添加新行时都发送一个 AddLine(...);，等待回复，然后再针对下一行执行此操作。客户端现在可以决定如何以最佳方式对要绘制的大型线条集合进行划分。
如果只是单纯地实现，我们会发现服务器和客户端完全不同步：客户端可以使用无界限的 AddLines(...); 调用对服务器进行泛洪处理，而服务器同样可能向客户端填充超出其处理能力的 -> OnDrawn(...); 事件。这两个问题的解决方案就是添加一个简单的 Ready() -> (); 方法以进行同步。每当客户端准备好接收下一次绘图更新时，都会调用此方法，并且来自服务器的响应表明客户端可以继续处理更多请求。
现在，我们在两个方向上都进行了一些流控制。该协议现在实现了前馈模式，允许在某个同步的“提交”调用触发服务器上的实际工作之前进行许多不受控制的调用。这可以防止客户端处理大量工作，导致服务器不堪重负。同样，不再允许服务器发送无界限 -> OnDrawn(...); 事件：每个事件都必须遵循来自客户端的一个信号，即 Ready() -> (); 调用，这表示它已准备好执行更多工作。这称为节流事件模式。
具体实现必须手动应用其中某些规则：如果客户端收到其未通过 Ready() -> (); 方法请求的 -> OnDrawn(...); 事件，则必须关闭连接。
FIDL、CML 和 Realm 接口定义如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.canvas.clientrequesteddraw;
/// A point in 2D space.
type Point = struct {
x int64;
y int64;
};
/// A line in 2D space.
alias Line = array<Point, 2>;
/// A bounding box in 2D space. This is the result of "drawing" operations on our canvas, and what
/// the server reports back to the client. These bounds are sufficient to contain all of the
/// lines (inclusive) on a canvas at a given time.
type BoundingBox = struct {
top_left Point;
bottom_right Point;
};
/// Manages a single instance of a canvas. Each session of this protocol is responsible for a new
/// canvas.
@discoverable
open protocol Instance {
/// Add multiple lines to the canvas. We are able to reduce protocol chatter and the number of
/// requests needed by batching instead of calling the simpler `AddLine(...)` one line at a
/// time.
flexible AddLines(struct {
lines vector<Line>;
});
/// Rather than the server randomly performing draws, or trying to guess when to do so, the
/// client must explicitly ask for them. This creates a bit of extra chatter with the additional
/// method invocation, but allows much greater client-side control of when the canvas is "ready"
/// for a view update, thereby eliminating unnecessary draws.
///
/// This method also has the benefit of "throttling" the `-> OnDrawn(...)` event - rather than
/// allowing a potentially unlimited flood of `-> OnDrawn(...)` calls, we now have the runtime
/// enforced semantic that each `-> OnDrawn(...)` call must follow a unique `Ready() -> ()` call
/// from the client. An unprompted `-> OnDrawn(...)` is invalid, and should cause the channel to
/// immediately close.
flexible Ready() -> ();
/// Update the client with the latest drawing state. The server makes no guarantees about how
/// often this event occurs - it could occur multiple times per board state, for example.
flexible -> OnDrawn(BoundingBox);
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.canvas.clientrequesteddraw.Instance" },
],
config: {
// A script for the client to follow. Entries in the script may take one of two forms: a
// pair of signed-integer coordinates like "-2,15:4,5", or the string "READY". The former
// builds a local vector sent via a single `AddLines(...)` call, while the latter sends a
// `Ready() -> ()` call pauses execution until the next `->OnDrawn(...)` event is received.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use a vector of `union { Point; Ready}` here.
script: {
type: "vector",
max_count: 100,
element: {
type: "string",
max_size: 64,
},
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.canvas.clientrequesteddraw.Instance" },
],
expose: [
{
protocol: "examples.canvas.clientrequesteddraw.Instance",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.canvas.clientrequesteddraw.Instance",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{format_err, Context as _, Error},
config::Config,
fidl_examples_canvas_clientrequesteddraw::{InstanceEvent, InstanceMarker, Point},
fuchsia_component::client::connect_to_protocol,
futures::TryStreamExt,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send Instance requests
// across the channel.
let instance = connect_to_protocol::<InstanceMarker>()?;
println!("Outgoing connection enabled");
let mut batched_lines = Vec::<[Point; 2]>::new();
for action in config.script.into_iter() {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if action == "PUSH" {
instance.add_lines(&batched_lines).context("Could not send lines")?;
println!("AddLines request sent");
batched_lines.clear();
continue;
}
// If the next action in the script is to "WAIT", block until an OnDrawn event is received
// from the server.
if action == "WAIT" {
let mut event_stream = instance.take_event_stream();
loop {
match event_stream
.try_next()
.await
.context("Error getting event response from proxy")?
.ok_or_else(|| format_err!("Proxy sent no events"))?
{
InstanceEvent::OnDrawn { top_left, bottom_right } => {
println!(
"OnDrawn event received: top_left: {:?}, bottom_right: {:?}",
top_left, bottom_right
);
break;
}
InstanceEvent::_UnknownEvent { ordinal, .. } => {
println!("Received an unknown event with ordinal {ordinal}");
}
}
}
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
println!("Ready request sent");
instance.ready().await.context("Could not send ready call")?;
println!("Ready success");
continue;
}
// Add a line to the next batch. Parse the string input, making two points out of it.
let mut points = action
.split(":")
.map(|point| {
let integers = point
.split(",")
.map(|integer| integer.parse::<i64>().unwrap())
.collect::<Vec<i64>>();
Point { x: integers[0], y: integers[1] }
})
.collect::<Vec<Point>>();
// Assemble a line from the two points.
let from = points.pop().ok_or(format_err!("line requires 2 points, but has 0"))?;
let to = points.pop().ok_or(format_err!("line requires 2 points, but has 1"))?;
let mut line: [Point; 2] = [from, to];
// Batch a line for drawing to the canvas using the two points provided.
println!("AddLines batching line: {:?}", &mut line);
batched_lines.push(line);
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{anyhow, Context as _, Error},
fidl::endpoints::RequestStream as _,
fidl_examples_canvas_clientrequesteddraw::{
BoundingBox, InstanceRequest, InstanceRequestStream, Point,
},
fuchsia_async::{Time, Timer},
fuchsia_component::server::ServiceFs,
fuchsia_zircon::{self as zx},
futures::future::join,
futures::prelude::*,
std::sync::{Arc, Mutex},
};
// A struct that stores the two things we care about for this example: the bounding box the lines
// that have been added thus far, and bit to track whether or not there have been changes since the
// last `OnDrawn` event.
#[derive(Debug)]
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
changed: bool,
// Tracks whether or not the client has declared itself ready to receive more updated.
ready: bool,
bounding_box: BoundingBox,
}
/// Handler for the `AddLines` method.
fn add_lines(state: &mut CanvasState, lines: Vec<[Point; 2]>) {
// Update the bounding box to account for the new lines we've just "added" to the canvas.
let bounds = &mut state.bounding_box;
for line in lines {
println!("AddLines printing line: {:?}", line);
for point in line {
if point.x < bounds.top_left.x {
bounds.top_left.x = point.x;
}
if point.y > bounds.top_left.y {
bounds.top_left.y = point.y;
}
if point.x > bounds.bottom_right.x {
bounds.bottom_right.x = point.x;
}
if point.y < bounds.bottom_right.y {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next tick.
state.changed = true
}
/// Creates a new instance of the server, paired to a single client across a zircon channel.
async fn run_server(stream: InstanceRequestStream) -> Result<(), Error> {
// Create a new in-memory state store for the state of the canvas. The store will live for the
// lifetime of the connection between the server and this particular client.
let state = Arc::new(Mutex::new(CanvasState {
changed: true,
ready: true,
bounding_box: BoundingBox {
top_left: Point { x: 0, y: 0 },
bottom_right: Point { x: 0, y: 0 },
},
}));
// Take ownership of the control_handle from the stream, which will allow us to push events from
// a different async task.
let control_handle = stream.control_handle();
// A separate watcher task periodically "draws" the canvas, and notifies the client of the new
// state. We'll need a cloned reference to the canvas state to be accessible from the new
// task.
let state_ref = state.clone();
let update_sender = || async move {
loop {
// Our server sends one update per second, but only if the client has declared that it
// is ready to receive one.
Timer::new(Time::after(zx::Duration::from_seconds(1))).await;
let mut state = state_ref.lock().unwrap();
if !state.changed || !state.ready {
continue;
}
// After acquiring the lock, this is where we would draw the actual lines. Since this is
// just an example, we'll avoid doing the actual rendering, and simply send the bounding
// box to the client instead.
let bounds = state.bounding_box;
match control_handle.send_on_drawn(&bounds.top_left, &bounds.bottom_right) {
Ok(_) => println!(
"OnDrawn event sent: top_left: {:?}, bottom_right: {:?}",
bounds.top_left, bounds.bottom_right
),
Err(_) => return,
}
// Reset the change and ready trackers.
state.ready = false;
state.changed = false;
}
};
// Handle requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
let state_ref = &state;
let request_handler =
stream.map(|result| result.context("failed request")).try_for_each(|request| async move {
// Match based on the method being invoked.
match request {
InstanceRequest::AddLines { lines, .. } => {
println!("AddLines request received");
add_lines(&mut state_ref.lock().unwrap(), lines);
}
InstanceRequest::Ready { responder, .. } => {
println!("Ready request received");
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();`
// event; if two "consecutive" `Ready() -> ();` calls are received, this
// interaction has entered an invalid state, and should be aborted immediately.
let mut state = state_ref.lock().unwrap();
if state.ready == true {
return Err(anyhow!("Invalid back-to-back `Ready` requests received"));
}
state.ready = true;
responder.send().context("Error responding")?;
} //
InstanceRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
});
// This line will only be reached if the server errors out. The stream will await indefinitely,
// thereby creating a long-lived server. Here, we first wait for the updater task to realize the
// connection has died, then bubble up the error.
join(request_handler, update_sender()).await.0
}
// A helper enum that allows us to treat a `Instance` service instance as a value.
enum IncomingService {
Instance(InstanceRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Instance` protocol - this will allow the client to see
// the server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Instance);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Instance(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/client_requested_draw/cpp_natural/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::AsyncEventHandler<examples_canvas_clientrequesteddraw::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(
fidl::Event<examples_canvas_clientrequesteddraw::Instance::OnDrawn>& event) override {
::examples_canvas_clientrequesteddraw::Point top_left = event.top_left();
::examples_canvas_clientrequesteddraw::Point bottom_right = event.bottom_right();
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y() << " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_clientrequesteddraw::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_clientrequesteddraw::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_clientrequesteddraw::Point(x, y);
}
using Line = ::std::array<::examples_canvas_clientrequesteddraw::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_clientrequesteddraw::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
fit::result<fidl::Error> result = client->AddLines(batched_lines);
if (!result.is_ok()) {
// Check that our one-way call was enqueued successfully, and handle the error
// appropriately. In the case of this example, there is nothing we can do to recover here,
// except to log an error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLines request: " << result.error_value();
return -1;
}
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
FX_LOGS(INFO) << "Ready request sent";
client->Ready().ThenExactlyOnce(
[&](fidl::Result<examples_canvas_clientrequesteddraw::Instance::Ready> result) {
// Check if the FIDL call succeeded or not.
if (result.is_ok()) {
FX_LOGS(INFO) << "Ready success";
} else {
FX_LOGS(ERROR) << "Could not send Ready request: " << result.error_value();
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x() << ", y: " << line[1].y()
<< " }, Point { x: " << line[0].x() << ", y: " << line[0].y() << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples_canvas_clientrequesteddraw::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_clientrequesteddraw::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLines(AddLinesRequest& request, AddLinesCompleter::Sync& completer) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : request.lines()) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x()
<< ", y: " << points[1].y() << " }, Point { x: " << points[0].x()
<< ", y: " << points[0].y() << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x() < bounds.top_left().x()) {
bounds.top_left().x() = point.x();
}
if (point.y() > bounds.top_left().y()) {
bounds.top_left().y() = point.y();
}
if (point.x() > bounds.bottom_right().x()) {
bounds.bottom_right().x() = point.x();
}
if (point.y() < bounds.bottom_right().y()) {
bounds.bottom_right().y() = point.y();
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void Ready(ReadyCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if two
// "consecutive" `Ready() -> ();` calls are received, this interaction has entered an invalid
// state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
completer.Reply();
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_clientrequesteddraw::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client has
// not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto result = fidl::SendEvent(binding_)->OnDrawn(state_.bounding_box);
if (!result.is_ok()) {
return;
}
auto top_left = state_.bounding_box.top_left();
auto bottom_right = state_.bounding_box.bottom_right();
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y()
<< " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
// Reset the change and ready trackers.
state_.ready = false;
state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_clientrequesteddraw::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++（有线）
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/client_requested_draw/cpp_wire/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler
: public fidl::WireAsyncEventHandler<examples_canvas_clientrequesteddraw::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(
fidl::WireEvent<examples_canvas_clientrequesteddraw::Instance::OnDrawn>* event) override {
::examples_canvas_clientrequesteddraw::wire::Point top_left = event->top_left;
::examples_canvas_clientrequesteddraw::wire::Point bottom_right = event->bottom_right;
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_clientrequesteddraw::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_clientrequesteddraw::wire::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_clientrequesteddraw::wire::Point{.x = x, .y = y};
}
using Line = ::fidl::Array<::examples_canvas_clientrequesteddraw::wire::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_clientrequesteddraw::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
fidl::Status status = client->AddLines(fidl::VectorView<Line>::FromExternal(batched_lines));
if (!status.ok()) {
// Check that our one-way call was enqueued successfully, and handle the error
// appropriately. In the case of this example, there is nothing we can do to recover here,
// except to log an error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLines request: " << status.error();
return -1;
}
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
FX_LOGS(INFO) << "Ready request sent";
client->Ready().ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_canvas_clientrequesteddraw::Instance::Ready>&
result) {
// Check if the FIDL call succeeded or not.
if (result.ok()) {
FX_LOGS(INFO) << "Ready success";
} else {
FX_LOGS(ERROR) << "Could not send Ready request: " << result.error();
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples_canvas_clientrequesteddraw::wire::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_clientrequesteddraw::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLines(AddLinesRequestView request, AddLinesCompleter::Sync& completer) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : request->lines) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void Ready(ReadyCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if two
// "consecutive" `Ready() -> ();` calls are received, this interaction has entered an invalid
// state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
completer.Reply();
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_clientrequesteddraw::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client has
// not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = weak->state_.bounding_box.top_left;
auto bottom_right = weak->state_.bounding_box.bottom_right;
fidl::Status status =
fidl::WireSendEvent(weak->binding_)->OnDrawn(top_left, bottom_right);
if (!status.ok()) {
return;
}
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change and ready trackers.
state_.ready = false;
weak->state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_clientrequesteddraw::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/canvas/clientrequesteddraw/cpp/fidl.h>
#include <examples/fidl/new/canvas/client_requested_draw/hlcpp/client/config.h>
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples::canvas::clientrequesteddraw::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples::canvas::clientrequesteddraw::Point{.x = x, .y = y};
}
using Line = ::std::array<::examples::canvas::clientrequesteddraw::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace, then create an asynchronous client
// using the newly-established connection.
examples::canvas::clientrequesteddraw::InstancePtr instance_proxy;
auto context = sys::ComponentContext::Create();
context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
FX_LOGS(INFO) << "Outgoing connection enabled";
instance_proxy.set_error_handler([&loop](zx_status_t status) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
loop.Quit();
});
// Provide a lambda to handle incoming |OnDrawn| events asynchronously.
instance_proxy.events().OnDrawn =
[&loop](::examples::canvas::clientrequesteddraw::Point top_left,
::examples::canvas::clientrequesteddraw::Point bottom_right) {
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop.Quit();
};
instance_proxy.events().handle_unknown_event = [](uint64_t ordinal) {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << ordinal;
};
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
instance_proxy->AddLines(batched_lines);
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are ready
// for us.
FX_LOGS(INFO) << "Ready request sent";
instance_proxy->Ready([&](fpromise::result<void, fidl::FrameworkErr> result) {
if (result.is_error()) {
// Check that our flexible two-way call was known to the server and handle the case of an
// unknown method appropriately. In the case of this example, there is nothing we can do
// to recover here, except to log an error and exit the program.
FX_LOGS(ERROR) << "Server does not implement AddLine";
}
FX_LOGS(INFO) << "Ready success";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>
#include <lib/async/cpp/task.h>
#include <lib/fidl/cpp/binding.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/canvas/clientrequesteddraw/cpp/fidl.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples::canvas::clientrequesteddraw::BoundingBox bounding_box;
};
using Line = ::std::array<::examples::canvas::clientrequesteddraw::Point, 2>;
// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::clientrequesteddraw::Instance {
public:
// Bind this implementation to an |InterfaceRequest|.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::InterfaceRequest<examples::canvas::clientrequesteddraw::Instance> request)
: binding_(fidl::Binding<examples::canvas::clientrequesteddraw::Instance>(this)),
weak_factory_(this) {
binding_.Bind(std::move(request), dispatcher);
// Gracefully handle abrupt shutdowns.
binding_.set_error_handler([this](zx_status_t status) mutable {
if (status != ZX_ERR_PEER_CLOSED) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
});
// Start the update timer on startup. Our server sends one update per second.
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLines(std::vector<Line> lines) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : lines) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next
// |OnDrawn| event.
state_.changed = true;
}
void Ready(ReadyCallback callback) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if
// two "consecutive" `Ready() -> ();` calls are received, this interaction has entered an
// invalid state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
callback(fpromise::ok());
}
void handle_unknown_method(uint64_t ordinal, bool method_has_response) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something
// has changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client
// has not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = state_.bounding_box.top_left;
auto bottom_right = state_.bounding_box.bottom_right;
binding_.events().OnDrawn(top_left, bottom_right);
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change and ready trackers.
state_.ready = false;
state_.changed = false;
},
after);
}
fidl::Binding<examples::canvas::clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from
// the client. The following initializes the loop, and obtains the dispatcher, which will be
// used when binding the server implementation to a channel.
//
// Note that unlike the new C++ bindings, HLCPP bindings rely on the async loop being attached
// to the current thread via the |kAsyncLoopConfigAttachToCurrentThread| configuration.
async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component.
// This directory is where the outgoing FIDL protocols are installed so that they can be
// provided to other components.
auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
context->outgoing()->AddPublicService(
fidl::InterfaceRequestHandler<examples::canvas::clientrequesteddraw::Instance>(
[dispatcher](
fidl::InterfaceRequest<examples::canvas::clientrequesteddraw::Instance> request) {
// Create an instance of our |InstanceImpl| that destroys itself when the connection
// closes.
new InstanceImpl(dispatcher, std::move(request));
}));
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
联合载荷
FIDL 方案：联合载荷
联合载荷是使用 union 布局的 FIDL 方法载荷。用作方法载荷的顶级类型必须使用 struct、table 或 union 之一作为其布局。值得注意的是，一些生成的绑定会“扁平化”传递给 struct 方法载荷的参数，以便每个成员本身在调用签名中被视为函数参数。使用 table 或 union 的载荷永远不会执行该操作，并且始终会传递一个名为 payload 的参数。
推理
键值对存储基准示例的实现是一个很好的起点，但一个主要缺点是数据存储为原始字节。FIDL 是一种类型丰富的语言。例如，强制将 UTF-8 字符串存储为非类型字节数组的数据，对于 *.fidl 文件的读取器以及使用从该文件生成的绑定的编程人员来说，都会清除这些有价值的类型信息。
实现
这项更改的主要目标是将基准用例的 vector<byte> 类型 value 成员替换为用于存储许多可能类型的 union。事实上，经过此次变更，您可以很好地了解 FIDL 的值类型：
- FIDL 的所有内置标量类型在
Valueunion中用作变体：bool、uint8、uint16、uint32、uint64、int8、int16、int32、int64、float32和float64（也称为 FIDL 的基元类型）以及string。 - 此
union还包含使用 FIDL 的内置array<T, N>和vector<T>类型模板的功能。 - 此示例中使用 FIDL 的所有类型布局（即
bits、enum、table、union和struct）至少一次。
用于 WriteItem 的请求和响应载荷也已分别从 struct 更改为命名的 table 和内嵌的 flexible union。事实上，这三种布局中的任何一种均可用作请求/响应负载。后两者（分别称为表载荷和 *联合载荷）在除消息大小对最敏感的用例之外，是首选。这是因为将来以与二进制文件兼容的方式扩展这些变量会更容易。
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.usegenericvalues;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value Value;
};
// Because the `Value` must be used both in the request and the response, we give it its own named
// type. The type is a `union` of all possible data types that we take as values, and is marked
// `flexible` to allow for the easy addition of new data types in the future.
type Value = flexible union {
// Keep the original `bytes` as one of the options in the new union.
1: bytes vector<byte>:64000;
// A `string` is very similar to `vector<byte>` on the wire, with the extra constraint that
// it enforces that it enforces that the byte vector in question is valid UTF-8.
2: string string:64000;
// All of FIDL's primitive types.
3: bool bool;
4: uint8 uint8;
5: int8 int8;
6: uint16 uint16;
7: int16 int16;
8: uint32 uint32;
9: int32 int32;
10: float32 float32;
11: uint64 uint64;
12: int64 int64;
13: float64 float64;
// FIDL does not natively support 128-bit integer types, so we have to define our own
// representations.
14: uint128 array<uint64, 2>;
};
// Because we now supoprt a richer range of types as values in our store, it is helpful to use a
// `flexible`, and therefore evolvable, `bits` type to store write options.
type WriteOptions = flexible bits : uint8 {
// This flag allows us to overwrite existing data when there is a collision, rather than failing
// with an `WriteError.ALREADY_EXISTS`.
OVERWRITE = 0b1;
// This flag allows us to concatenate to existing data when there is a collision, rather than
// failing with an `WriteError.ALREADY_EXISTS`. "Concatenation" means addition for the numeric
// variants and appending to the `bytes`/`string` variants. If no existing data can be found, we
// "concatenate" to default values of zero and an empty vector, respectively. Attempting to
// concatenate to an existing variant of a different type will return a
// `WriteError.INVALID_VALUE` error.
CONCAT = 0b10;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
///
/// Since the value stored in the key-value store can now be different from the input (if the
/// `WriteOptions.CONCAT` flag is set), we need to return the resulting `Value` to the
/// requester.
///
/// We use an (anonymous) `table` and a (named) `flexible union` as the request and response
/// payload, respectively, to allow for easier future evolution. Both of these types are
/// `flexible`, meaning that adding or removing members is binary-compatible. This makes them
/// much easier to evolve that the `struct` types that were previously used, which cannot be
/// changed after release without breaking ABI.
flexible WriteItem(table {
1: attempt Item;
2: options WriteOptions;
}) -> (Value) error WriteError;
};
全渠道营销 (CML)
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
config: {
// A vector of values for every easily representible type in our key-value store. For
// brevity's sake, the 8, 16, and 32 bit integer types and booleans are omitted.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use all FIDL constructs directly here. In
// particular, floats and nested types are very difficult to represent, and have been
// excluded from this example for the time being.
set_concat_option: { type: "bool" },
set_overwrite_option: { type: "bool" },
write_bytes: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_strings: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
write_uint64s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
write_int64s: {
type: "vector",
max_count: 16,
element: { type: "int64" },
},
// Note: due to the limitation of structured config not allowing vectors nested in vectors,
// we only set the lower half of the uint128 for simplicity's sake.
write_uint128s: {
type: "vector",
max_count: 16,
element: { type: "uint64" },
},
},
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.usegenericvalues.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "self",
},
],
}
领域
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.usegenericvalues.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
然后，可以使用任何支持的语言编写客户端和服务器实现：
Rust
客户端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreMarker, StoreProxy, StoreWriteItemRequest, Value, WriteOptions,
},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
// A helper function to sequentially write a single item to the key-value store and print a log when
// successful.
async fn write_next_item(
store: &StoreProxy,
key: &str,
value: Value,
options: WriteOptions,
) -> Result<(), Error> {
// Create an empty request payload using `::default()`.
let mut req = StoreWriteItemRequest::default();
req.options = Some(options);
// Fill in the `Item` we will be attempting to write.
println!("WriteItem request sent: key: {}, value: {:?}", &key, &value);
req.attempt = Some(Item { key: key.to_string(), value: value });
// Send and async `WriteItem` request to the server.
match store.write_item(&req).await.context("Error sending request")? {
Ok(value) => println!("WriteItem response received: {:?}", &value),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
Ok(())
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// All of our requests will have the same bitflags set. Pull these settings from the config.
let mut options = WriteOptions::empty();
options.set(WriteOptions::OVERWRITE, config.set_overwrite_option);
options.set(WriteOptions::CONCAT, config.set_concat_option);
// The structured config provides one input for most data types that can be stored in the data
// store. Iterate through those inputs in the order we see them in the FIDL file.
//
// Note that FIDL unions are rendered as enums in Rust; for example, the `Value` union has now
// become a `Value` Rust enum, with each member taking exactly one argument.
for value in config.write_bytes.into_iter() {
write_next_item(&store, "bytes", Value::Bytes(value.into()), options).await?;
}
for value in config.write_strings.into_iter() {
write_next_item(&store, "string", Value::String(value), options).await?;
}
for value in config.write_uint64s.into_iter() {
write_next_item(&store, "uint64", Value::Uint64(value), options).await?;
}
for value in config.write_int64s.into_iter() {
write_next_item(&store, "int64", Value::Int64(value), options).await?;
}
for value in config.write_uint128s.into_iter() {
write_next_item(&store, "uint128", Value::Uint128([0, value]), options).await?;
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
服务器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
};
use {
fidl_examples_keyvaluestore_usegenericvalues::{
Item, StoreRequest, StoreRequestStream, Value, WriteError, WriteOptions,
},
std::collections::hash_map::OccupiedEntry,
std::ops::Add,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
/// Sums any numeric type.
fn sum<T: Add + Add<Output = T> + Copy>(operands: [T; 2]) -> T {
operands[0] + operands[1]
}
/// Clones and inserts an entry, so that the original (now concatenated) copy may be returned in the
/// response.
fn write(inserting: Value, mut entry: OccupiedEntry<'_, String, Value>) -> Value {
entry.insert(inserting.clone());
println!("Wrote key: {}, value: {:?}", entry.key(), &inserting);
inserting
}
/// Handler for the `WriteItem` method.
fn write_item(
store: &mut HashMap<String, Value>,
attempt: Item,
options: &WriteOptions,
) -> Result<Value, WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY for key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
// The `CONCAT` flag supersedes the `OVERWRITE` flag, so check it first.
if options.contains(WriteOptions::CONCAT) {
match entry.get() {
Value::Bytes(old) => {
if let Value::Bytes(new) = attempt.value {
let mut combined = old.clone();
combined.extend(new);
return Ok(write(Value::Bytes(combined), entry));
}
}
Value::String(old) => {
if let Value::String(new) = attempt.value {
return Ok(write(Value::String(format!("{}{}", old, &new)), entry));
}
}
Value::Uint64(old) => {
if let Value::Uint64(new) = attempt.value {
return Ok(write(Value::Uint64(sum([*old, new])), entry));
}
}
Value::Int64(old) => {
if let Value::Int64(new) = attempt.value {
return Ok(write(Value::Int64(sum([*old, new])), entry));
}
}
// Note: only works on the uint64 range in practice.
Value::Uint128(old) => {
if let Value::Uint128(new) = attempt.value {
return Ok(write(Value::Uint128([0, sum([old[1], new[1]])]), entry));
}
}
_ => {
panic!("actively unsupported type!")
}
}
// Only reachable if the type of the would be concatenated value did not match the
// value already occupying this entry.
println!("Write error: INVALID_VALUE for key: {}", entry.key());
return Err(WriteError::InvalidValue);
}
// If we're not doing CONCAT, check for OVERWRITE next.
if options.contains(WriteOptions::OVERWRITE) {
return Ok(write(attempt.value, entry));
}
println!("Write error: ALREADY_EXISTS for key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
println!("Wrote key: {}, value: {:?}", entry.key(), &attempt.value);
entry.insert(attempt.value.clone());
Ok(attempt.value)
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, Value>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
// Because we are using a table payload, there is an extra level of indirection. The
// top-level container for the table itself is always called "payload".
StoreRequest::WriteItem { payload, responder } => {
println!("WriteItem request received");
// Error out if either of the request table's members are not set.
let attempt = payload.attempt.context("required field 'attempt' is unset")?;
let options = payload.options.context("required field 'options' is unset")?;
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(
write_item(&mut store.borrow_mut(), attempt, &options)
.as_ref()
.map_err(|e| *e),
)
.context("error sending reply")?;
println!("WriteItem response sent");
} //
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++（自然）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++（有线）
客户端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
服务器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
客户端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
服务器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.