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-cliredis-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
Add this line to your application's Gemfile:
gem 'rdkit'And then execute:
$ bundle
Or install it yourself as:
$ gem install rdkit
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.
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.startThis will start a TCPServer on 0.0.0.0:3721 and stops when you CTRL-C.
@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
endYou 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
endYou 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
endSee examples under example folder.
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$ 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
$ 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 secondSince it is single-threaded, the count will be correct:
127.0.0.1:3721> count
(integer) 10000Some 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
endRunning:
$ 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?
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.
| 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 |
| command | description |
|---|---|
gc |
start garbage collection immediately |
heapdump |
ObjectSpace.dump_all to ./tmp |
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.
- 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