Sarav's Weblog

Technical Articles for RoR Developers

Apache Thrift with Ruby – A basic Tutorial

Thrift is a software framework for scalable cross-language services development. It combines a software stack with a code generation engine to build services that work efficiently and seamlessly between C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, Smalltalk, and OCaml.

Originally developed at Facebook, Thrift was open sourced in April 2007 and entered the Apache Incubator in May, 2008.

Thrift is arguably one of the best lightweight systems for cross-language programming using code-generation, RPC, and object serialization. Designed from the ground up by the Facebook development team it enables seamless integration of the most commonly used languages (Ruby, Perl, C/C++, Haskell, Python, Java, and more) via a set of common RPC libraries and interfaces.

In this post I’ll outline how to setup and connect a thrift client in ruby

To install thrift

gem install thrift


  • Defining a thrift service
  • Run the server script(ruby)
  • Run the client script(ruby)

Defining a service in Thrift

The core goal of Thrift is to enable efficient and reliable communications across multiple languages. All datatypes and services are defined in a single language-neutral file and the necessary code is auto-generated for the developer by the thrift compiler.

One of the great things about thrift is that it simplifies the communication between a client and server to a simple .thrift file. This file describes the data structures, and functions available to your remote service. In this tutorial, we use a simple calculator mechanism.

Define a struct and a service

	enum BinaryOperation {

	/** Structs are the basic complex data structures. They are comprised of fields 
	   * which each have an integer identifier, a type, a symbolic name, and an 
	   * optional default value. */
	struct ArithmeticOperation {
		1:BinaryOperation op,
		2:double lh_term,
		3:double rh_term,

	/* Structs can also be exceptions, if they are nasty. */
	exception ArithmeticException {
		1:string msg,
		2:optional double x,

	service Calculator {

		* A method definition looks like C code. It has a return type, arguments,
		* and optionally a list of exceptions that it may throw. Note that argument
		* lists and exception lists are specified using the exact same syntax as
		* field lists in struct or exception definitions.
		double calc(1:ArithmeticOperation op) throws (1:ArithmeticException ae),
		* This method has an oneway modifier. That means the client only makes
		* a request and does not listen for any response at all. Oneway methods
		* must be void.
		* The server may execute async invocations of the same client in parallel/
		* out of order.
		oneway void run_task()

Open a empty file and create service(copy the above code) and save it with .thrift extension(eg:calc.thrift)

We’ve defined two different functions: remote calculationand an asynchronous method call. To generate the required code, we simply call the thrift generator:

# Generate C++, Ruby, and Python implementations
# generated code will be in ‘gen-cpp’, ‘gen-rb’, ‘gen-py’ folder

thrift --gen rb calc.thrift

The beauty of this approach is, of course, the ability to mix and match implementations of services: server may be written in C++, but we can access it seamlessly via a Python, Java, or a Ruby client. Thrift will take care of the communications links, object serialization, and socket management!

Implementing a Thrift powered server in Ruby

A very simple example of interaction with a calculator server application whose actions are facilitated by thrift. Both the client and server negotiate on the common interface defined by calc.thrift.

# include thrift-generated code

require 'thrift'
require 'calculator'

# provide an implementation of Calculator
class CalculatorHandler
	def initialize()
		#nothing goes here

	def calc(val)
		lh_term = val.lh_term
		rh_term = val.rh_term
		case val.op
			when 1 #Addition
			when 2 #subraction
			when 3 #multiplication
			when 4 #division
			when 5	#modulas
	def run_task()
		puts "Kicking off the task"

# Thrift provides mutiple communication endpoints
#  - Here we will expose our service via a TCP socket
#  - Web-service will run as a single thread, on port 9090

handler =
processor =
transport =
transportFactory =
server =, transport, transportFactory)
puts "Starting the Calculator server..."
puts "done."

To expose our thrift service, we wrap it into a TCP socket listening on port 9090. From this point on, Thrift takes over all communications, serialization and handling of the incoming requests. Because the protocol is identical in every language, the client may be written in any language of choice.

Building the Ruby Client

You may have the client program in any language which supports Thrift.

In similar fashion, we can build a Ruby client for any Thrift service with just a few lines of code. To interface with our server implementation above, refer the following code:

# include thrift-generated code

require 'thrift'
require 'calculator'

	port = ARGV[0] || 9090

	transport ='localhost', 9090))
	protocol =
	client =

	ar =    
	ar.op = BinaryOperation::ADDITION
	ar.lh_term = 99
	ar.rh_term = 3
	# Run a remote calculation
	result = client.calc(ar)  #it accessing the ruby server program method calc via thrift service
	puts result.inspect
	#Run a Async call
	puts $!

And there you have it, a simple thrift client. I hope you think about thrift next time you need to interface between 2 applications, or require some kind of client->server model for your system. Thrift makes it very fast and convenient to share data across different programming languages and makes it easy/flexible to develop to a shared interface contract. Cheers!

Download Files


  • Download the calc.thrift and place it into the new folder(name it whatever you like. Eg:- thrift-ruby)
  • cd thrift-ruby
  • thrift –gen rb calc.thrift (it will create the auto generated ruby code. Dont change anything on the auto generated code)
  • create the folder named “rb” and place the ruby_server.rb and ruby_client.rb
  • run server program first. $ruby ruby_server.rb (it will start the server)
  • then run the client program in new cmd prompt. $ruby ruby_client.rb



4 responses to “Apache Thrift with Ruby – A basic Tutorial

  1. Anonymous June 27, 2011 at 5:43 pm

    Thanks Its very useful

  2. Anonymous September 27, 2012 at 5:04 am

    shouldn’t the transport.close() be in an ensure block? else thrift errors will result in connections not being closed, and eventual server crash if server runs out of connections.

  3. Chamila Wijayarathna June 6, 2014 at 9:40 am

    Thanks, this is very useful, what are the different protocols and layered transports supported by ruby?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: