This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit a590023f5a40f0b3f6dd927b67ed802b5a810def Author: chaokunyang <[email protected]> AuthorDate: Sun Aug 2 17:15:50 2026 +0000 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/' --- docs/compiler/compiler-guide.md | 7 ++++-- docs/compiler/generated-code.md | 50 +++++++++++++++++++++++++++++++++++++++++ docs/compiler/index.md | 26 +++++++++++---------- 3 files changed, 69 insertions(+), 14 deletions(-) diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md index 323e9a19d8..abe4721f8b 100644 --- a/docs/compiler/compiler-guide.md +++ b/docs/compiler/compiler-guide.md @@ -149,15 +149,18 @@ foryc user.fdl order.fdl product.fdl --output ./generated foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript ``` -**Generate Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and Node.js JavaScript gRPC service companions:** +**Generate Java, Python, Go, Rust, C++, C#, Dart, Scala, Kotlin, and Node.js JavaScript gRPC service companions:** ```bash -foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc +foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --cpp_out=./generated/cpp --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` The generated gRPC service code uses Fory to serialize request and response payloads. Java output imports grpc-java APIs, Python output defaults to `grpc.aio`, Go output imports grpc-go, Rust output imports `tonic` and `bytes`, +C++ output includes gRPC C++ `grpcpp` headers; targets compiling it must add the +generated output directory to their include path and link `fory::serialization` +and `gRPC::grpc++`. Scala output imports grpc-java APIs, and Kotlin output imports grpc-java and grpc-kotlin APIs and uses coroutine stubs. C# output imports `Grpc.Core.Api` types and can be hosted with normal .NET gRPC packages such as `Grpc.AspNetCore` diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md index 7c8d79cf29..6e19369453 100644 --- a/docs/compiler/generated-code.md +++ b/docs/compiler/generated-code.md @@ -610,6 +610,8 @@ class Person final { void set_number(Arg&& arg, Args&&... args); fory::Result<std::vector<uint8_t>, fory::Error> to_bytes() const; + static fory::Result<PhoneNumber, fory::Error> from_bytes( + const uint8_t* data, std::size_t size); static fory::Result<PhoneNumber, fory::Error> from_bytes(const std::vector<uint8_t>& data); }; @@ -721,6 +723,54 @@ auto bytes = person.to_bytes(); auto restored = addressbook::Person::from_bytes(bytes.value()); ``` +### gRPC Service Companions + +When a schema contains services and the compiler is run with `--grpc`, C++ +generation emits a service API header file and gRPC binding files. For a schema +header named `addressbook.h`, those files are `addressbook.service.h`, +`addressbook.service.grpc.h`, and `addressbook.service.grpc.cc`. + +The service API header file contains synchronous business interfaces and gRPC path +constants under `::<schema namespace>::service`: + +```cpp +namespace addressbook::service { + +class AddressBookService { + public: + virtual ~AddressBookService() = default; + + virtual ::grpc::Status Lookup( + ::grpc::ServerContext* context, + const ::addressbook::Person* request, + ::addressbook::AddressBook* response) = 0; +}; + +inline constexpr char AddressBookServiceServiceName[] = + "addressbook.AddressBookService"; +inline constexpr char AddressBookServiceLookupPath[] = + "/addressbook.AddressBookService/Lookup"; + +} // namespace addressbook::service +``` + +The gRPC binding header file and source file contain Fory-backed codecs, generated +`grpc::SerializationTraits` specializations, and synchronous client/server +wrappers under `::<schema namespace>::service::grpc`. They serialize each +request or response with the generated model type's `to_bytes` and `from_bytes` +helpers: + +```cpp +template <> +class SerializationTraits<::addressbook::Person, void> + : public ::fory::grpc::detail::ForyGrpcSerializationTraits< + ::addressbook::Person> {}; +``` + +Applications compiling the generated C++ service files must provide gRPC C++ +1.39.0 or later and link the generated `.service.grpc.cc` file with Fory +serialization. + ## Go ### Output Layout diff --git a/docs/compiler/index.md b/docs/compiler/index.md index caa69a6fc9..4d89c46343 100644 --- a/docs/compiler/index.md +++ b/docs/compiler/index.md @@ -23,9 +23,9 @@ Fory IDL is a schema definition language for Apache Fory that enables type-safe cross-language serialization. Define your data structures once and generate native data structure code for Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. Fory IDL can also -describe RPC services; for Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and -JavaScript, the compiler can generate gRPC service companions that use Fory -serialization for request and response payloads. +describe RPC services; for Java, Python, Go, Rust, C++, C#, Dart, Scala, Kotlin, +and JavaScript, the compiler can generate gRPC service companions that use +Fory serialization for request and response payloads. ## Example Schema @@ -88,21 +88,23 @@ service AnimalService { } ``` -Generate Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and JavaScript models -plus gRPC service companions with: +Generate Java, Python, Go, Rust, C++, C#, Dart, Scala, Kotlin, and JavaScript +models plus gRPC service companions with: ```bash -foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc +foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --cpp_out=./generated/cpp --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` The generated service code uses normal gRPC APIs, but request and response objects are serialized with Fory. Applications provide their own grpc-java, grpc-kotlin, Scala grpc-java APIs, `grpcio`, grpc-go, Rust `tonic` and `bytes`, -C# `Grpc.Core.Api` and hosting/client dependencies, or Dart `package:grpc`; Fory -packages do not add gRPC as a hard dependency. Python companions use `grpc.aio` -by default and can be generated in sync mode with `--grpc-python-mode=sync`. -JavaScript Node.js companions use `@grpc/grpc-js`; browser clients are generated -separately with `--grpc-web` and use `grpc-web`. +gRPC C++ 1.39.0 or later, C# `Grpc.Core.Api` and hosting/client dependencies, or +Dart `package:grpc`; Fory packages do not add gRPC as a hard dependency. See +[C++ gRPC Support](../guide/cpp/grpc-support.md) for C++ linking instructions. +Python companions use `grpc.aio` by default and can be generated in sync mode +with `--grpc-python-mode=sync`. JavaScript Node.js companions use +`@grpc/grpc-js`; browser clients are generated separately with `--grpc-web` and +use `grpc-web`. ## Why Fory IDL? @@ -176,7 +178,7 @@ message Person { foryc example.fdl --output ./generated # Generate for specific languages -foryc example.fdl --lang java,python,csharp,javascript,swift,dart,scala,kotlin --output ./generated +foryc example.fdl --lang java,python,cpp,csharp,javascript,swift,dart,scala,kotlin --output ./generated ``` ### 4. Use Generated Code --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
