This chapter introduces Apache Thrift’s RPC services as the centerpiece of the framework, showing how service interfaces declared in IDL are compiled into language-specific clients and processors that enable seamless cross-language calls. User-defined types serialize across any supported protocol, while transports such as TCP sockets or domain sockets carry messages between processes—or even within a single process. The generated Client exposes the service locally to callers, and the Processor dispatches requests to a user-implemented Handler on the server. Together, these pieces allow developers to write backend functionality in one language and consume it from many others with minimal glue code.
Implementing a service follows a clear path: declare the service in IDL, compile to generate stubs, write a handler that fulfills the interface, host it with a server using a transport and protocol, and consume it with the generated client. The chapter recommends testing handlers in-process first for speed and debuggability, then wiring up a server (for example, TServerSocket + TSimpleServer) and clients (TSocket + TBinaryProtocol), ensuring protocol and transport alignment. It emphasizes robust interface design: assign stable positive parameter IDs, rely on default requiredness, and provide default parameter values so older clients remain compatible. Servers ignore unknown parameters, enabling incremental rollout without synchronized deploys across an enterprise.
Beyond the basics, the chapter details service evolution (adding or removing parameters and methods) and the compatibility implications for old and new clients, demonstrating safe patterns like adding parameters with defaults or introducing new methods. It covers generated artifacts—Iface, Client, Processor, factories, and the *_args/*_result structs—and explains the message flow and types (T_CALL, T_REPLY, T_EXCEPTION, T_ONEWAY). Advanced features include oneway methods for fire-and-forget notifications, service inheritance via extends to build layered APIs without altering existing IDL, and optional asynchronous client models (callbacks or futures) where supported. The overarching theme is building evolvable, testable, multi-language services that can be upgraded incrementally with strong backward compatibility.
The Apache Thrift RPC service layer.
Apache Thrift remote procedure call processing.
Function parameter components.
The Apache Thrift framework provides all the features required to seamlessly move embedded modules into standalone services.
A typical RPC message exchange between a service client and service processor.
Summary
Apache Thrift Services are collections of functions that can be called remotely using Apache Thrift RPC. The range of features provided by the Apache Thrift framework make Apache Thrift RPC a good fit for modern, evolving, multi-language enterprises.
Apache Thrift Services are composed of sets of functions.
Functions have a set of parameters and use parameter Ids, requiredness, and default values to enable interface evolution.
Through interface evolution, multiple versions of a particular service interface can coexist in a production environment.
Services are implemented by user-coded handlers.
Handlers can be built into the client process and called directly for testing and debugging purposes.
RPC operations are handled by an IDL generated client object on the client side and a processor object on the server side.
The client object exposes an interface identical to that of the handler implementing the service.
The client object forwards RPC calls to the server-based processor that dispatches calls to the handler.
RPC is implemented with messages (CALL, REPLY, EXCEPTION and ONEWAY).
Functions can be declared oneway in Apache Thrift IDL, which causes the function to transmit the parameters to the server without waiting for or receiving a reply of any kind.
Services can inherit from other services using the extends keyword.
Apache Thrift doesn’t support overriding or overloading functions; a service handler must implement all the service methods, including those inherited, precisely once.
Each programming language supported by Apache Thrift provides its own specific files for generated RPC code.
FAQ
What are the basic steps to implement an Apache Thrift service?1) Declare the service interface in Thrift IDL. 2) Run the Thrift compiler to generate code for your target languages. 3) Implement a handler class that provides the service logic. 4) Create a server using the generated Processor plus a transport, protocol, and server class. 5) Build clients using the generated Client with matching transport and protocol.What does the Thrift compiler generate for each service?- Iface: the language-specific service interface. - Client: the client-side proxy that invokes remote methods. - Processor: the server-side dispatcher that calls your handler. - IfFactory/ProcessorFactory: factories some servers use to create per-connection instances. - func_args structs: one per method to serialize parameters. - func_result structs: one per method to serialize return values or declared exceptions.How do Thrift clients and servers connect and serialize data?- Transport: provides the communication channel (for example, TSocket/TServerSocket over TCP). - Protocol: defines serialization (for example, TBinaryProtocol). - Both ends must use compatible transport endpoints and the same protocol. - The generated Client writes calls over the protocol/transport; the Processor reads them and invokes your handler.How should I assign parameter identifiers (IDs), and why do they matter?- Always assign unique positive 16-bit IDs (preferably sequential) to every parameter. - Avoid relying on compiler-assigned negative IDs; reordering parameters will renumber them and break compatibility. - If you inherit an IDL without IDs, you can annotate the existing (negative) IDs to match generated code and use the -allow-neg-keys flag to silence warnings.What does parameter requiredness mean for service methods?- required: must always be present; removing or changing it is a breaking change and many languages will throw if missing. - default (no keyword): servers should not assume it is present; allows adding or removing the parameter over time. - optional is not supported for parameters (only for struct fields). To model optional inputs, pass a struct whose fields can be optional.How do default parameter values work, and how do they aid compatibility?- Defaults are applied on the server when a client that doesn’t know about a parameter omits it. - Required parameters ignore defaults (clients must send them; servers will error if missing). - Clients must still pass all parameters that exist in their version of the interface; Thrift does not auto-fill defaults on the client side.How can I evolve a service interface without breaking existing clients?- Add a parameter: safe if you provide a default; old clients omit it, new servers use the default. - Remove a parameter: new clients can call old servers only if the removed parameter originally had a default (old servers ignore unknown parameters, not missing ones). - Add a method: old clients keep working; new clients must tolerate “not implemented” on old servers. - Remove a method: old clients will fail unless they handle “not implemented.” - Use stable, positive parameter IDs to preserve compatibility.What are oneway functions, and when should I use them?- Oneway methods send a request and do not receive any response (no return value or exceptions back). - Benefits: reduced round-trips and immediate client return after writing the request. - Caveats: you cannot tell if the call succeeded; you cannot evolve a normal method to oneway (or vice versa) without breaking changes; oneway should be void and exceptions cannot be propagated.What is service inheritance, and what rules apply?- A service can extend another service to reuse its methods (extends keyword). - You must implement all inherited methods in the derived service’s handler. - No method overloading or overriding is allowed and no two methods may share the same name in the hierarchy. - A server implementing the derived service implicitly supports clients of the base service.What happens “under the hood” during a Thrift RPC call?- The client sends a message with method name, type, and sequence number, followed by the method_args struct. - The server Processor reads the message and args, calls your handler, then writes back a method_result struct. - Message types: T_CALL (client request), T_REPLY (server normal reply or declared user exception), T_EXCEPTION (framework-level error like invalid method), T_ONEWAY (no reply expected).
pro $24.99 per month
access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
Programmer’s Guide to Apache Thrift ebook for free
