The most naive approach is to run a piece of code as a separate process (or thread). The code spins a loop where it receives messages, dispatches them and sleeps for some time. You could see such a pattern in some of the previous posts ( Pattern: Agent Life Cycle).

Another approach is to use scheduling. An agents schedules its next activities to certain times. This approach is usually advantageous for long- and sparsely-running agents. A good example can be monitoring agent, a news-sending agent, or even plain-old UNIX maintenance scripts, etc..
Here, again, we can choose from two methods of scheduling:

1. The agent determines only the very next time of its execution.
2. The agents uses a full static schedule - execution plan.

The former method is very dynamic, flexible allowing the agent adopt its behavior immediately. However, it can be vulnerable to possible errors. An error can cause the agent won’t register anymore. In fact it becomes dead. The later method is predictable and suitable for static environments.

In the rest of this post I demonstrate how easy it can be to operate a cron driven “agent” directly from your Ruby code.

Cron Scheduling

You can decide to use Ruby native scheduler (like rufus-scheduler), or rely on an external service (like Unix Cron, or other dedicated middleware). This time I show you how to engage with Unix Cron scheduling (next time I tell you more about other schedulers.) Well, for simple cases you can edit cron manually, i.e. install your schedule using crontab. But for more complex and dynamic cases this is a pain in the ass. Imagine you have dozens (or hundreds) of autonomous agents running on your system, or you have very frequent schedule modifications. The CronEdit library help us out here.
Install it as a gem:

sudo gem install cronedit

or get it from its project home.

CronEdit library associates each cron entry with an id. This makes it uniquely manipulable and not interfering with other entries. It is because the rest of the actual crontab is left unchanged. So you can manipulate the crontab as comfortable as it was a Hash. Your cron entry definition itself can have a standard cron text format, or alternatively you can use Hash notation. Let’s look at few simple examples.

Simple operations using class methods

require 'cronedit'
include CronEdit
Crontab.Add  :agent1, '5,35 0-23/2 * * * echo 123'
Crontab.Add  :agent2, {:minute=>5, :command=>'ruby /agents/agent.rb 42'}
Crontab.Remove 'agent1', 'agent2'

The first line registers a cron entry in standard text notation under id ‘agent1 ‘. The second line registers entry ‘agent2′ using Hash notation. The last line deletes both entries. The changes are effective immediately. You can list all actual entries by:

p Crontab.List

Batch/transactional updates
In case you need to do more changes at once use the following approach

cm = CronEdit::Crontab.new
cm.add 'agent1', '5,35 0-23/2 * * * echo agent1'...
cm.add 'agent2', {:minute=>5, :command=>'echo 42'}
cm.remove 'agentKiller'
cm.commit

Inversely, you can also rollback the operations.

Bulk update/removal using file definitions
In more complex scenarios (communities of agenst) you often need to manipulate more agents at once with their definitions in files. Imagine you have a crowd of news-gathering agents and mail-analysis agents. The cron definitions for these groups are stored as files (previously generated by CronEdit)

fc = FileCrontab.new '/agents/news-gathering.cron'
Crontab.Merge fc...
Crontab.Subtract fc

The first line uses FileCrontab to read the cron definition of all news-gathering agents. The file crontab is merged in to the actual system crontab on the next line. Similarly the definitions can be ‘unloaded’ using ’subtract’ method.

The library allows you do even more (e.g. when you definitions are in DB; combining multiple definitions)
See more examples and documentation.

In the next posts I present another simple piece of the infrastructure helpful for this type of agents.

Solution: The solution is to use a modified Boolean Flag Pattern, where the flag specific operation is to break the loop for reading an n-tuple, i.e. the Agent Life Cycle pattern.

(life cycle, boolean flag and shutdown flag patterns)

loop do
  begin
    read or take n-tuple with timeout t1

  rescue Rinda::RequestExpiredError

    begin
      read the shutdown flag with timeout t2

      break # stop listening for the n-tuple

    rescue Rinda::RequestExpiredError

      # ignore a situation when there is no shutdown flag

    end

    next # repeat the loop

  end

  process n-tuple
end

Example:

(life cycle, boolean flag and shutdown flag patterns)

loop do
  begin
    t = ts.take [:plus, nil, nil], 10

  rescue Rinda::RequestExpiredError

    begin
      ts.read [:end], 1

      break # stop listening for the n-tuple

    rescue Rinda::RequestExpiredError

      # ignore a situation when there is no shutdown flag

    end

    next # repeat the loop

  end

  res = t[1] + t[2]
  ts.write [:result, res]
end

Solution: The solution is to set a timeout for a read or take operation, where the timeout value specifies how often a flag appearance should be checked, and if the flag is presented to perform the flag specific operation.

The Agent Life Cycle pattern is, of course, used too.

(life cycle and boolean flag patterns)

loop do
  begin
    read or take n-tuple with timeout t1

  rescue Rinda::RequestExpiredError

    begin
      read the flag n-tuple with timeout t2
      perform a flag specific operation
    rescue Rinda::RequestExpiredError
      perform an operation when the flag is not set
    end

    next # repeat the loop

  end

  process n-tuple
end

Solution: The solution is to perform operation read or take in a loop.

loop do
  read or take n-tuple

  process n-tuple
end

Example:

loop do
  t = ts.take [:plus, nil, nil]

  res = t[1] + t[2]
  ts.write [:result, res]
end

Comments:
The method process should execute agent’s duty :), there is only questionable, if it should:

• start a new thread, to process the loaded n-tuple, and immediately listen for a next n-tuple
• or it should process the loaded n-tuple, and when the processing is finished, to start listening for a next n-tuple.

I would prefer the second way - it is more agent-like, it is not mixing threads and agents concepts (including managing agents vs managing threads) - if you would like to process more n-tuples in parallel, simply start another agent instance.

Example:

• To read a tuple and if there is no such tuple, to wait 4 seconds for it:

  ts.read [nil, nil], 4
  

• Or to take a tuple and if there is no such tuple, to wait 1 minute for it:

  ts.take [nil, nil], 60
  

There are two special values that you may use as a timeout value:

• 0 (zero) - an operation would not wait at all. It is useful for checking, if a n-tuple is stored in the blackboard or not.
• nil - an operation would wait endlessly. Of course, there is not difference if you would call an operation without a specified timeout value or with nil.
  Actually, to be more precise, an operation would wait 2³¹ - 1 seconds, that is approximately 30 years. ;)

But what would happen, if we specify a timeout value and an n-tuple would not appear on the blackboard in the specified time(out)?
Rinda throws the Rinda::RequestExpiredError exception.

The handling exceptions in Ruby is very comfortable (esp. with the command retry). An example follows, where a tuple is taken with a timeout 5 seconds. This allows to inform an user about the state, that the application is still waiting for a message:

puts "Waiting for a message."
begin
  t = ts.take [:message, nil], 5
rescue Rinda::RequestExpiredError
  puts “Still waiting for a message.”
  retry
end

The timeout functionality allows to:

• create a responsiveness application - to inform other components or users about its state (e.g. waiting for a message - processing a message).
• end an application normally - to break waiting for a n-tuple every so often and check if the application should end.
• check for different n-tuples - it is possible to wait in deferent intervals for different n-tuples. Of course, a better solution is to create for each n-tuple an own thread that performs a blackboard access operation for this particular n-tuple.
• create an application that does not access a blackboard all the time (e.g. only every hour for 1 minute).

The example shows how to:

• Create an agent.
• Locate the blackboard.
• Write a tuple (a calculator operation).
• Take a tuple (a calculator operation result).
• Differentiate between different operations (plus and minus).
• Handle a simple ID.

The calculator agent will be able to handle two kinds of operations: plus and minus. It will receive an operation request tuple, where one item will be an operation identifier (to handle two operations) and two items with numerical values (to transmit values).
The agent will produce a result tuple, where one item will be a numerical value (to transmit back a result value).
To track a result, each operation request tuple will have an ID, that will be inserted back into a result tuple.

To sum up, there will be two tuple types:

• operation request [:calculator, id, operation, a, b], e.g.
  [:calculator, id, :plus, 1, 2] or [:calculator, id, :minus, 6, 2].




• result [:result, id, value], e.g.
  [:result, id, 4].

To run this example, we will need three files: rinda.rb to start the environment, calculator.rb the calculator agent and client.rb to send requests and display results.

The calculator agent source code, calculator.rb:

require 'rinda/ring'
require 'rinda/tuplespace'

# A simple calculator example.
#
class SimpleCalculator

  def plus(a, b)
    a + b
  end

  def minus(a, b)
    a - b
  end

  def main
    DRb.start_service
    ts = Rinda::RingFinger.primary

    loop do
      t = ts.take [:calculator, nil, nil, nil, nil] # take an operation request

      # assign values
      id = t[1]
      operation = t[2]
      arg1 = t[3]
      arg2 = t[4]

      puts “Calculator recived operation ##{id} #{operation} with arguments #{arg1} and #{arg2}”

      res = operation == ‘plus’ ? plus(arg1, arg2) : minus(arg1, arg2) # perform the received operation
      #sleep 1 # to pretend that an operation takes longer

      ts.write [:result, id, res] # send a result back
    end
  end
end

SimpleCalculator.new.main

And the client source code, client.rb:

require 'rinda/ring'

DRb.start_service

ts = Rinda::RingFinger.primary

t1 = Time.now #the start time

# sending operation requests

id = 1 # the ID
for i in (1..5) # plus operations
  puts "Sending operation ##{id} plus with arguments #{i} and 1"
  ts.write [:calculator, id, :plus, i, 1]
  id += 1 # an unique ID value
end
for i in (5..9) # minus operations
  puts “Sending operation ##{id} minus with arguments #{i} and 1″
  ts.write [:calculator, id, :minus, i, 1]
  id += 1 # an unique ID value
end

puts “Waiting for results…”

# receiving results

i = 1
loop do
  t = ts.take [:result, nil, nil], 2
  puts “Result ##{t[1]} = #{t[2]}”
  i += 1
  break if i > 10 # 10 request were sent
end

t2 = Time.now # the end time
puts “The operation took #{t2 - t1} seconds.”

See a screencast

To start the example, firstly start the environment ruby rinda.rb and then start the calculator agent ruby calculator.rb. Each execution of the client, ruby client.rb, will produce 10 operation requests that will be processed by the agent. The agent will produce 10 results, that will be read by the client.

There is a lot of log messages, so you can easily see when an agent instance received a request, when it send a result and when a client send a request and received a result. With the #id part of a log message you can track particular communication parts.

Execution time should be very short, approx. 0.06 seconds.


Let’s imagine that an operation processing would take longer, e.g. 1 second. Uncomment the 32^nd line in the agent source code calculator.rb and restart all parts of the example (rinda.rb and calculator.rb).
Execute the client and the execution time will be, as expected, 10.06 seconds.


And now, to show power of a parallel processing in a multi-agent system, start another calculator agent…

The logs of the started calculator agent instances show that the processing load was nicely shared between the agents.

The result? A half of time (of course), approx. 5.04 seconds.

I like it :)

Files to download: simple_calculator.zip.

The following functionalities will be shown:

• Creation of an agent.
• Locating the blackboard.
• Read a message.

The agent source code is stored in the read.rb file:

require 'rinda/ring'

DRb.start_service

ts = Rinda::RingFinger.primary

result = ts.read [:message, nil], 0

puts “[0]: #{result[0]}”
puts “[1]: #{result[1]}”

See a screencast .

Firstly, start the rinda.rb code (for more details see the post about starting multi-agent system environment), then, in a separate console, start the write.rb (for more details see the post about writing a message to the blackboard) and finally, in a separate console or in the same console where you started the write.rb file, type:

ruby read.rb

The agent connects to the blackboard, reads a tuple and shows two lines:

[0]: message
[1]: Hi there!

Of course, you could repeat this step any number of times, because this operation only checks if a tuple is there.

Files to download: rinda.rb, write.rb and read.rb.

What is a tuple?

• [1, 2] is a tuple
• [:message, 'Hi there!'] is a tuple
• ['Hi there!', :message] is also a tuple
• [:result, 42, 'John', 'Susanne', 'London'] is a tuple
• [:clock, Time.new] is a tuple too
• [:service, CalculatorService.new(1, true) is a tuple

Tuple is an ordered list of elements [wikipedia].

A blackboard is a place to share tuples; agents are writing, reading and taking tuples.

If you have a simple system, where agents are using only one kind of messages, it is enough to use a single, e.g. [1], ['Hello']. But what to do, if your system requires to differentiate more types of messages? Well, there is no problem with writing different types of messages, but there is a problem how to find the correct one to read or take it.

Basically there are two possibilities:

• Every type of a message has different number of elements. The number of elements is the distinguishing sign.

  Example: [1] is similar to [2] or ['Hello'], but it is different then [3, 'Hello'].

• One of the parameters is an identifier. The number of elements and an identifier are the distinguishing signs.

  Example: [:request, 1, 2] is similar to [:request, 24, 'John'], but it is different to [:result, 42, 'London'].

How are the blackboard operations using tuples?

• The write operation writes a tuple (specified as a parameter).

  ts.write [:message, 'Hi there!']
  

• Reading operations read and take use tuples in a slightly different way. It is possible to use the nil value as a wild card for the position, where it is used.
  • To read any single:

    ts.take [nil], 0
    

  • To read any pair:

    ts.take [nil, nil], 0
    

  • To read any :message type:

    ts.take [:message, nil], 0
    

  • To read any pair, where the second element has value 4 (not very practical example :):

    ts.take [nil, 4], 0
    

  • To read exactly the tuple [:result, 4]:

    ts.take [:result, 4], 0
    

  The second parameter says, how long (in seconds) should a read operation wait until a tuple appears on the blackboard. Zero means to not to wait at all.

The following functionalities will be shown:

• Creation of an agent.
• Locating the blackboard.
• Taking a message.

Although a logical opposite operation to the write operation should be the read operation, it is not so in the blackboard system: the operation read only checks if a message is there (this will be shown in a post that will follow); the operation take takes a message from the blackboard.

The agent source code is stored in the take.rb file:

require 'rinda/ring'

DRb.start_service

ts = Rinda::RingFinger.primary

result = ts.take [:message, nil], 0

puts “[0]: #{result[0]}”
puts “[1]: #{result[1]}”

Firstly, start the rinda.rb code (for more details see the post about starting multi-agent system environment), then, in a separate console, start the write.rb (for more details see the post about writing a message to the blackboard) and finally, in a separate console or in the same console where you started the write.rb file, type:

ruby take.rb

The agent connects to the blackboard, takes a message and shows two lines:

[0]: message
[1]: Hi there!

Files to download: rinda.rb, write.rb and take.rb.