RDKit
RDKit
is a simple toolkit to write Redis-like, single-threaded multiplexing-IO server.
The server speaks Redis RESP protocol, so you can reuse many Redis-compatible clients and tools such as:
redis-cli
redis-benchmark
- Redic
And a lot more.
RDKit
is used to power:
- 520 Love Radio service of same.com
- AntiSpam blacklisted photo filtering service used at same.com (BK-Tree + pHash)
- channel unread count service at same.com
RDKit
should work without problem on MRI
2.2+, may encounter bugs on earlier version of MRI
or JRuby
or Rubinus
, in that case, please kindly open an issue on GitHub
Installation
Add this line to your application's Gemfile:
gem 'rdkit'
And then execute:
$ bundle
Or install it yourself as:
$ gem install rdkit
Usage
Generally, you should implement one subclass for each of the 3 classes: RDKit::RESPResponder
, RDKit::Core
and RDKit::Server
, and spawn one object for each class.
Your server object should have two instance variables @responder
and @core
pointed to your spawned instances.
RDKit::Server
class YourServer < RDKit::Server
def initialize
super('0.0.0.0', 3721)
@core = YourCore.new
@responder = YourResponder.new(core)
end
end
server = YourServer.new
trap(:INT) { server.stop }
server.start
This will start a TCPServer
on 0.0.0.0:3721
and stops when you CTRL-C
.
RDKit::RESPResponder
@responder
maps Redis commands to its methods and arguments, for example info
will be sent to RESPResponder#info
, and info all
to RESPResponder#info
with "all"
as its first argument.
The return ruby object of each method will be marshaled as RESP strings, for example 'OK'
becomes "+OK\r\n"
.
For example, with following implementation in your RESPResponder
subclass:
def add(a, b)
a.to_i + b.to_i
end
You implemented an adder using RDKit! See it in action:
$ redis-cli -p 3721
127.0.0.1:3721> add 1 2
(integer) 3
127.0.0.1:3721> add 5
(error) ERR wrong number of arguments for 'add' command
127.0.0.1:3721>
The detailed algorithm can be found in resp.rb
, at the time of writing it is like this:
def compose(data)
case data
when *%w{ OK string list set hash zset none }
"+#{data}\r\n"
when true
":1\r\n"
when false
":0\r\n"
when Integer
":#{data}\r\n"
when Array
"*#{data.size}\r\n" + data.map { |i| compose(i) }.join
when NilClass
# Null Bulk String, not Null Array of "*-1\r\n"
"$-1\r\n"
when WrongTypeError
"-WRONGTYPE #{data.message}\r\n"
when StandardError
"-ERR #{data.message}\r\n"
else
# always Bulk String
"$#{data.bytesize}\r\n#{data}\r\n"
end
end
RDKit::Core
You are required to implement a tick!
method. RDKit
will call it periodically (currently roughly every 0.1 sec), this gives you a chance to do some house-keeping. For example:
def tick!
save_non_critical_data! if server.cycles % 1000 == 0
end
Examples
See examples under example
folder.
Implementing a counter server
A simple counter server source code listing:
require 'rdkit'
# counter/version.rb
module Counter
VERSION = '0.0.1'
end
# counter/core.rb
module Counter
class Core < RDKit::Core
attr_accessor :count
def initialize
@count = 0
@last_tick = Time.now
end
# `tick!` is called periodically by RDKit
def tick!
@last_tick = Time.now
end
def incr(n)
@count += n
end
def introspection
{
counter_version: Counter::VERSION,
count: @count,
last_tick: @last_tick
}
end
end
end
# counter/command_runner.rb
module Counter
class CommandRunner < RDKit::RESPRunner
def initialize(counter)
@counter = counter
end
# every public method of this class will be accessible by clients
def count
@counter.count
end
def incr(n=1)
@counter.incr(n.to_i)
end
end
end
# counter/server.rb
module Counter
class Server < RDKit::Server
def initialize
super('0.0.0.0', 3721)
# @core is required by RDKit
@core = Core.new
# @runner is also required by RDKit
@runner = CommandRunner.new(@core)
end
def introspection
super.merge(counter: @core.introspection)
end
end
end
# start server
server = Counter::Server.new
trap(:INT) { server.stop }
server.start
Connect using redis-cli
$ redis-cli -p 3721
127.0.0.1:3721> count
(integer) 0
127.0.0.1:3721> incr
(integer) 1
127.0.0.1:3721> incr 10
(integer) 11
127.0.0.1:3721> count
(integer) 11
127.0.0.1:3721> info
# Server
rdkit_version:0.0.1
multiplexing_api:select
process_id:15083
tcp_port:3721
uptime_in_seconds:268
uptime_in_days:0
hz:10
# Clients
connected_clients:1
connected_clients_peak:1
# Memory
used_memory_rss:31.89M
used_memory_peak:31.89M
# Counter
counter_version:0.0.1
count:11
last_tick:2015-05-27 20:15:38 +0800
# Stats
total_connections_received:1
total_commands_processed:6
127.0.0.1:3721> xx
(error) ERR unknown command 'xx'
Hint: if you are adventurous, try info all
Benchmarking with redis-benchmark
$ redis-benchmark -p 3721 incr
====== count ======
10000 requests completed in 0.73 seconds
50 parallel clients
3 bytes payload
keep alive: 1
0.01% <= 1 milliseconds
2.27% <= 2 milliseconds
42.31% <= 3 milliseconds
63.99% <= 4 milliseconds
96.14% <= 5 milliseconds
...
99.97% <= 68 milliseconds
99.98% <= 71 milliseconds
99.99% <= 74 milliseconds
100.00% <= 77 milliseconds
13679.89 requests per second
Since it is single-threaded, the count will be correct:
127.0.0.1:3721> count
(integer) 10000
Implementing blocked commands
Some commands will be blocking: they may either depend on external services or need some background tasks to be run.
The clients will expect those commands to be blocking calls, they will not return until the commands are finished, but we don't want the server to be blocked as well.
Therefore we introduce Server#blocking
methods, execution wrapped in this method call will be run in a background thread pool, and the client will be on hold until that task is finished.
Example: see examples/blocking
folder.
# blocking/command_runner.rb
module Blocking
class CommandRunner < RDKit::RESPRunner
attr_reader :core
def initialize(core)
@core = core
end
def block_with_callback
core.block_with_callback
# this is ignored, instead `on_success` block of `core.block_with_callback` is evaluated and returned
'OK'
end
def block
core.block
'OK'
end
def nonblock
core.nonblock
'OK'
end
end
end
# blocking/core.rb
module Blocking
class Core < RDKit::Core
def block_with_callback
on_success = lambda { 'success' }
server.blocking(on_success) { do_something }
end
def block
server.blocking { do_something }
end
def nonblock
do_something
end
def do_something
sleep 1
end
def tick!
end
end
end
Running:
$ redis-cli -p 3721
127.0.0.1:3721> block
OK
(1.03s)
127.0.0.1:3721> nonblock
OK
(1.01s)
127.0.0.1:3721> block_with_callback
"success"
(1.02s)
Benchmarking:
$ redis-benchmark -p 3721 -n 10 block
====== block ======
10 requests completed in 1.03 seconds
50 parallel clients
3 bytes payload
keep alive: 1
10.00% <= 1027 milliseconds
100.00% <= 1027 milliseconds
9.73 requests per second
$ redis-benchmark -p 3721 -n 10 nonblock
====== nonblock ======
10 requests completed in 10.04 seconds
50 parallel clients
3 bytes payload
keep alive: 1
10.00% <= 1001 milliseconds
20.00% <= 2005 milliseconds
30.00% <= 3010 milliseconds
40.00% <= 4013 milliseconds
50.00% <= 5018 milliseconds
60.00% <= 6022 milliseconds
70.00% <= 7027 milliseconds
80.00% <= 8030 milliseconds
90.00% <= 9034 milliseconds
100.00% <= 10039 milliseconds
1.00 requests per second
See the difference between blocking and non-blocking commands?
Additional IO Handler Injection
Since RDKit version 0.1.5, it allows injection of additional IO handlers into the main loop.
For examples, please refer to examples/ioinject
for an injected UDP echo server.
Implemented Redis Commands
command | support | note |
---|---|---|
info |
full | additional objspace and gc commands |
ping |
full | |
echo |
full | |
time |
full | |
select |
partial/compatible |
redis-benchmark requires select command |
config |
get , set , resetstat
|
|
slowlog |
full | |
client |
getname , setname , list , kill
|
kill filter only supports id , addr
|
monitor |
full | |
debug |
sleep , segfault
|
|
shutdown |
full | |
get |
full | |
set |
without options | |
del |
full | |
keys |
without pattern (return all) | |
lpush |
full | |
lpop |
full | |
rpop |
full | |
llen |
full | |
lrange |
partial (not fully tested) | |
exists |
full | |
flushdb |
full | |
flushall |
full | |
mget |
full | |
mset |
full | |
strlen |
full | |
sadd |
full | |
scard |
full | |
smembers |
full | |
sismember |
full | |
srem |
full | |
hset |
full | |
hget |
full | |
hexists |
full | |
hlen |
full | |
hstrlen |
full | |
hdel |
full | |
hkeys |
full | |
hvals |
full | |
setnx |
full | |
getset |
full |
Implemented Additional Commands
command | description |
---|---|
gc |
start garbage collection immediately |
heapdump |
ObjectSpace.dump_all to ./tmp |
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run bin/console
for an interactive prompt that will allow you to experiment.
Contributing
- Fork it ( https://github.com/forresty/rdkit/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request