Ruby API support¶

Status¶

The uWSGI API for Ruby is still incomplete (QueueFramework, SharedArea, custom routing and SNMP being the most missing players). The DSL will be extended as soon as the various API calls are ready.

Currently available API functions and constants (available in the UWSGI ruby module) are

UWSGI.suspend
UWSGI.masterpid
UWSGI.async_sleep
UWSGI.wait_fd_read
UWSGI.wait_fd_write
UWSGI.async_connect
UWSGI.signal
UWSGI.register_signal
UWSGI.register_rpc
UWSGI.signal_registered
UWSGI.signal_wait
UWSGI.signal_received
UWSGI.add_cron
UWSGI.add_timer
UWSGI.add_rb_timer
UWSGI.add_file_monitor
UWSGI.cache_get
UWSGI.cache_get!
UWSGI.cache_exists
UWSGI.cache_exists?
UWSGI.cache_del
UWSGI.cache_set
UWSGI.cache_set
UWSGI.cache_set!
UWSGI.cache_update
UWSGI.cache_update!
UWSGI.setprocname
UWSGI.set_warning_message
UWSGI.lock
UWSGI.unlock
UWSGI.mem
UWSGI.mule_get_msg
UWSGI.request_id
UWSGI.mule_id
UWSGI.mule_msg
UWSGI.worker_id
UWSGI.log
UWSGI.logsize
UWSGI.i_am_the_spooler
UWSGI.send_to_spooler
UWSGI.spool
UWSGI::OPT
UWSGI::VERSION
UWSGI::HOSTNAME
UWSGI::NUMPROC
UWSGI::PIDFILE
UWSGI::SPOOL_OK
UWSGI::SPOOL_RETRY
UWSGI::SPOLL_IGNORE

uWSGI DSL¶

In parallel to the uWSGI API Python decorators, a DSL for Ruby is available, allowing elegant access to the uWSGI API.

The module is available as uwsgidsl.rb in the source distribution. You can put this code in your config.ru file, or use the rbrequire option to auto-include it.

timer(n, block)¶

Execute code at regular intervals.

timer 30 do |signum|
  puts "30 seconds elapsed"
end

rbtimer(n, block)¶

As timer, but using a red-black tree timer.

rbtimer 30 do |signum|
  puts "30 seconds elapsed"
end

filemon(path, block)¶

Execute code at file modifications.

filemon '/tmp' do |signum|
  puts "/tmp has been modified"
end

cron(hours, mins, dom, mon, dow, block)¶

Execute a task periodically using the CronInterface.

cron 20,16,-1,-1,-1 do |signum|
  puts "It's time for tea."
end

signal(signum, block)¶

Register code as a signal handler for the SignalFramework.

signal 17 do |signum|
  puts "Signal #{signum} was invoked."
end

postfork(block)¶

Execute code after each fork().

postfork do
  puts "uWSGI server called fork()"
end

rpc(name, block)¶

Register code as a uWSGI RPC Stack function.

rpc 'helloworld' do
    return "Hello World"
end

rpc 'advancedhelloworld' do |x,y|
    return "x = #{x}, y = #{y}"
end

mule(id?, block)¶

Execute code as a Mule brain.

mule 1 do # Run in mule 1
  puts "I am the mule #{UWSGI.mule_id}"
end

mule do # Run in first available mule
  puts "I am the mule #{UWSGI.mule_id}"
end

After the function returns, the mule will be brainless. To avoid this, put the code in a loop, or use muleloop.

muleloop(id?, block)¶

Execute code in a mule in looped context.

muleloop 3 do
  puts "I am the mule #{UWSGI.mule_id}"
  sleep(2)
end

SpoolProc¶

A subclass of Proc, allowing you to define a task to be executed in the Spooler.

# define the function
my_long_running_task = SpoolProc.new {|args|
  puts "I am a task"
  UWSGI::SPOOL_OK
}

# spool it
my_long_running_task.call({'foo' => 'bar', 'one' => 'two'})

MuleFunc¶

Call a function from any process (such as a worker), but execute in a mule

i_am_a_long_running_function = MuleFunc.new do |pippo, pluto|
  puts "i am mule #{UWSGI.mule_id} #{pippo}, #{pluto}"
end

i_am_a_long_running_function.call("serena", "alessandro")

The worker calls i_am_a_long_running_function() but the function will be execute asynchronously in the first available mule.

If you want to run the function on a specific mule, add an ID parameter. The following would only use mule #5.

i_am_a_long_running_function = MuleFunc.new 5 do |pippo,pluto|
  puts "i am mule #{UWSGI.mule_id} #{pippo}, #{pluto}"
end

i_am_a_long_running_function.call("serena", "alessandro")

Real world usage¶

A simple Sinatra app printing messages every 30 seconds:

# This is config.ru

require 'rubygems'
require 'sinatra'
require 'uwsgidsl'

timer 30 do |signum|
  puts "30 seconds elapsed"
end

get '/hi' do
  "Hello World!"
end

run Sinatra::Application

Or you can put your code in a dedicated file (mytasks.rb here)

require 'uwsgidsl'

timer 30 do |signum|
  puts "30 seconds elapsed"
end

timer 60 do |signum|
  puts "60 seconds elapsed"
end

and then load it with

uwsgi --socket :3031 --rack config.ru --rbrequire mytasks.rb --master --processes 4