Javier Acero

Consistent Design

2021-02-11T00:00:00+00:00

Consistency is usually a quality desired in the design of any system. Unfortunately it means different things depending on who you talk to. It is frequently interpreted as using a small set of reusable building blocks.

The promise “Design By Building Blocks” makes is that one will come up with a design that suits all features of your application. This design will be the silver bullet one can refer to when adding any functionality to the application. It will also become the standard by which you judge the architecture of any part of your product.

In most cases this “recipe” comes in the form of a prescribed set of layers, with a side of patterns and restrictions on how these layers communicate with each other. Base abstractions are also a frequent ingredient.

Tackling the median complexity

Any modern application today will provide dozens of features to its users. Even an MVP in a private beta will include a handful of them. Each one will have its level of complexity. In a well-designed system, the software’s complexity will reflect the complexity of the functionality it provides.

At any given time a software product will be composed of a few simple features, several average-complexity features, and a small number of very complex ones. The distribution of the complexity will likely resemble a normal one:

To find the target design, one focuses on the features that are close to the median-complexity. That guarantees that we are considering the most significant chunk of the system possible. We look into the commonalities these pieces have and infer the patterns and restrictions from them.

Advantages

In theory, your entire system follows the same architecture. This comes with a few perks:

The structure of new features should be known, even before working on them.
It should be relatively simple to introduce engineers to the codebase.
Engineers can walk away from the codebase, and come back knowing what to expect.
Maintenance costs should be minimized by the patterns and restrictions.
The costs of introducing new functionalities should be close to linear.

Problems

While the promise of a sliver bullet is tempting, one should be aware of the dangers ahead.

Over-engineering

The features on the left tail of the distribution suffer from over-engineering. The simpler the logic, the bigger the problem is. Boilerplate code and excessive indirection are some of the expected symptoms. These usually complicate the maintainability, making the application harder to understand and evolve.

Under-engineering

The features on the right tail of the distribution tend to be the most problematic of all. Frequently the complexity of the problem to tackle outgrows the prescribed patterns. Bloated abstractions are a frequent indicator that tends to be the source of bugs and burden maintainability.

It is also very frequent that these components end up being where the consistency breaks. The bloated abstractions are overflown by complexity and engineers refactor it away, ignoring the predefined set of building blocks. Usually, the organization overlooks this situation and believes that consistency is still in place.

The price of consistency

Keeping the patterns and restrictions consistent across a codebase is, by far, the biggest problem any company that attempts to come up with a building block-based consistent design will face.

As the feature count grows, it is bound to happen that the initially defined conventions are no longer a good fit for a more significant subset of the system. Maybe even some of the initial building blocks are pin-pointed as the cause of issues.

The time to evolve the design has come.

The colossal problem is that keeping consistency requires a tremendous effort from the organization. The parts of the system that are suffering issues have to be updated. On top of that, every other feature in the application needs to evolve as the building blocks are refined. It doesn’t matter if it has been working flawlessly and hasn’t required any maintenance in years.

Facing the level of effort this enterprise will require, most companies will surrender to the original recipe. Design problems will be worked around, or even worse, overlooked. Bugs will start to pile up. Time to market and development costs of new features will grow. Engineers will burn out dealing with repetitive issues, not able to tackle the root problems without breaking the consistency of the design.

A better approach to consistency

Rather than focusing on the pieces of the puzzle, focus on what you are trying to achieve with them. Decide what qualities you want your design to have, define them and make sure that those stay during the evolution of the system.

Some examples:

Modifiability: The system is easy to understand, modify and evolve.
Testability: The system design allows for thorough and easy automated testing.
Scalability: The system design allows for the service to be scaled.
Resiliency and fault tolerance: The system takes errors into consideration and handles them appropriately.
Observability and auditability: The system provides information about what happens inside it.

To make sure the architecture exhibits these qualities as it evolves you can define Fitness Functions to monitor them as described in Building Evolutionary Architectures.

It is imperative to allow for incremental changes to happen, adapting to increasing complexity. These may or may not cross-pollinate between subsets of the system when needed, without explicitly enforcing it.

A small set of loosely defined building blocks, patterns and restrictions are OK, to begin with, but always take them with a grain of salt. Be flexible and allow for rules to be broken. That’s were innovation starts.

Interesting content (January 2018)

2018-02-16T00:00:00+00:00

Running a little late this month, but here we go:

Talks

The art of destroying software by Greg Young

This one comes, again, from @eferro and his post about Simplicity for developers. I’ve been watching most of those talks in the past few weeks.

I loved this talk, even if it’s a guy talking to the camera for 40 minutes without slides. I usually enjoy all Greg Young’s talks. This one wasn’t an exception.

The main idea behind it is to focus on building systems from pieces (objects, actors, micro-services, components…) that you can easily delete and re-write. This has a lot of implications, specially when talking about technical debt.

The other main takeaway from the talk is that we are doing nothing new. This is something that you will hear from other reputed professionals: Uncle Bob shares this very same idea in Clean Architecture several times. Gary Bernhart has said the same thing in numerous occasions.

Books

January was a busy month, including a DNSimple meetup in Florida. I continued reading 99 bottles of OOP. I have just finished reading it but the review will have to wait until next month.

In the meantime you can watch this hypnotic video that @sbastn and I recorded on a windy day at Melbourne Beach.

Posts

Auto-squashing git commits by Thought Bot

This one came into my twitter timeline thanks to @amuino back in December but I didn’t have the chance to read it until January…

It introduces a couple features that you can use when rebasing that I wasn’t familiar with. It may encourage me to rebase more often than I usually do.

Read it here

Stop abusing NotImplementedError

I found this post in the comments of a talk on Youtube. Funny enough the author seems to have deleted it.

It explains why we should not use NotImplementedError when trying to mimic interfaces or abstract classes in Ruby. This is, to my knowledge, a widely used practice. Finding out about the details of this error was very enlightening to me.

Read it here

The modern dev team

This one was dropped in the DNSimple Slack channel.

There are 2 things that made me enjoy this post a lot:

Reflects on the fact that we keep resolving the same problems with different tools. Also says that Erlang solved this problems a long time ago and got most of the solutions right (which is a thought that I keep having more and more often).
Shares the view of a developer that just turned 50. We will all get there (🤞), so reading about the fears that will come may make it easier to grow older as a software engineer.

Read it here

Don’t cross the beams by Kent Beck

This is one was referenced on 99 bottles of OOP. Like pretty much everything that Kent Beck writes, this is a must read.

The post explains the difference between vertical and horizontal refactorings and why you should perform them in order rather than mix them.

Read it here

Interesting content (December 2017)

2018-01-07T00:00:00+00:00

Happy New Year everyone! I’m starting 2018 trying to go back to writing here from time to time.

Talks

The “right” way to ship software

By Jocelyn Goldfein former Engineer Director at Facebook (2010-2014) and VP of Engineering at VMWARE (2003-2010). The talk took place as part of hack.summit() 2016.

I found this one thanks to @eferro.

It’s a really thoughtful talk on how the way software is released is totally dependent on the context, and how it shapes companies, practices and the way we build software in general. Must watch. One of those talks that put into words things that seem obvious, but aren’t.

Watch it here.

Evolutionary architectures

Saw a few talks on the same topic:

One by Rebecca Parsons (@rebeccaparsons) CTO at ThoughtWorks. Watch it here.
One by Neal Ford (@neal4d) from ThoughtWorks. Watch it here.
One by Pat Kua (@patkua) CTO at N26, former ThoughtWorks. Watch it here.

I got these from this Twitter thread.

Talks present a, somewhat different, view of software architecture explaining how it can, and should, be the vehicle to allow guided, incremental, change.

Love the underlying concept and will certainly investigate more about the topic (in fact the book they wrote is already in my iPad and I’m looking forward to start it).

Neal’s and Pat’s are really the same talk delivered by two separate speakers. I liked Neal’s better. Rebecca’s is slightly different and addresses other interesting ideas. I re-watched Rebecca’s after watching Neal’s (and Pat’s) and I think you’ll get more value if you watch them in that order. Don’t expect technical details as the talks (and the topic) are more high level.

Books

Clean Architecture (Uncle Bob)

It’s been almost 6 years since Architecture: The Lost Years was published. That talk shook my world and caused quite some noise in the Ruby community. It pointed out everything that is wrong with The Rails Way (aka The Framework Way). The main complian about the talk was that it didn’t include any examples.

The database is a detail. The web is a detail. Frameworks are not your application.

Unfortunately the book doesn’t go much further than all the previous content that the author had already shared in blog posts, Clean Coders videos or talks. In that sense, it’s a “greatest hits compilation”. Most people will expect an in-depth example and won’t find it in the book either.

There are two things that I really enjoyed though:

Part II

In this section the author discusses the 3 main programming paradigms (Procedural, Object Oriented and Functional). It goes over the main traits of each one and explains how each one of them imposes restrictions on the programmer, which is a point of view that I had never heard of before.
The epilogue.

I’d buy the book only to read it.

In it the author goes over most of his career explaining what companies did he work for and what he did there. He explains the challenges he faced and what they did about them at the time. All of it sauced with pictures of the old computers and different devices that they were using at the time.

The Nature of Software Development (Ron Jeffries)

I was expecting a more technical book. I had read good reviews by some peers and went for it without really knowing what the book was about. Got very little out of it because I was familiar with most of the ideas discussed in it.

“Don’t worry—we’re not going to drop into programming—but we do want all our readers to be aware of what the business needs to expect of developers, and what it needs to support.”

It’s short and easy to read. Goes to the point and justifies everything clearly. It even points out something that most books about software processes ignore: to be able to build software iteratively (aka Agile Software Development) you need skilled developers.

Even though I didn’t get much out of it, I must say that, if I have ever have to recommend one book to anyone as an introduction to iterative software development, it will be this one. It is that good.

Posts

Managing your personal tech portfolio

This post got to my twitter feed (was retweeted by Neal Ford). Went through it quickly as it’s an easy read. It contains good advice to structure your learning. Most tips you probably have heard before, but I found two ideas really interesting:

Treating it as an investment portfolio was really appealing to me.
Having your own technology radar a la ThoughtWorks to guide learning.

Read it here

Excuses by Uncle bob.

I follow Uncle Bob, but it ended up in my timeline retweeted by several people I follow.

What can I say, I love pro-TDD rants and this post is one of those. I have tried to stay away from rants against or in favor of TDD for the last 4 years. I can’t believe our industry is still debating about this…

Read it here

Elixir code quality tools by Matt Gauger

This one was part of Elixir Radar issue 123.

Although I’m not a big fan of these type of tools (specially Rubocop), there are some useful ones in this post.

Read it here

The smell of that potion

2016-04-04T00:00:00+00:00

I’ve been using Ruby as my main programming language since 2010. As of today I still enjoy its syntax and simplicity. Its community is very friendly and productive and many companies and products have sprung from it.

However all these years have not been a path of roses. I have seen how the Ruby community has been deeply influenced by one big project: Ruby on Rails. The standards and conventions of that project were taken as the right way of using the language. There have been plenty of voices complaining about it yet the mainstream mentality hasn’t changed one bit.

The other problem that any Ruby developer will face sooner rather than later is performance. If there were people in the community warning about the Rails way of doing things the complains about the performance have been an outcry.

It’s been three years since this thought crossed my mind for the first time and I still think that Rails and the GIL will kill¹ Ruby. There are countless examples of how bad the maintainability of Rails applications gets as the code base grows. You will find even more cases of performance issues. There is a lesson to be learnt lurking in there. A lesson that I won’t easily forget when I choose my next go-to programming language.

Speaking of which: I have been playing with Elixir lately. It was a young language back in 2013 when I first tried it out. It’s more mature now. Several libraries and frameworks are making the language ecosystem more interesting. One of these projects is Phoenix.

Phoenix is a mayor player in the language now. Big enough to make creating a new Phoenix project a task in the language build tool, mix.

I have to admit that I haven’t given the framework a serious try yet. But all the demos and guides I have seen reminded me so much of Rails that I wanted to brew uninstall elixir immediately. While performance won’t be an issue, maintainability and bad practices may turn Elixir into the new Ruby.

It was a relief to find this article by José Valim (the creator of Elixir) while researching about testing and mocking tools. That blog post is a summary of the mocking and testing practices that I have been following and advocating for several years. I was super pleased not only to see that José advocates them too but also that the language has support for them right out of the box.

I am looking forward to give Phoenix a try. Hope all that Rails-iness is only a coat intended to create familiarity. Hope Elixir and its community embraces modularity and good design practices like Ruby never did. My fingers are crossed.

And by killing I mean significantly impacting the usage of the language. ↩

Starting with EventMachine IV

2013-06-15T00:00:00+00:00

This blog post is an extract of an ebook about EventMachine that I started writing some time ago. Somehow it ended up half written in some dark corner of my hard drive. I have decided to publish the material I have as series of posts. Please let me know if you find the material useful.

You can find all posts here:

Doing it the wrong way

For a long time Ruby’s threading issues have been a problem for application scalability and performance. EventMachine is a great tool to tackle that problem. But it’s no silver bullet. It has its drawbacks and you need to be aware of them in order to unleash all it’s potential.

Asynchronous I/O for your Ruby programs. The title of the book¹ already points to the kind of Ruby application that may take advantage of EventMachine’s capabilities. You won’t make a CPU-heavy program faster by throwing this library in (or any other reactor based library for that matter). The reactor is the heart and soul of EventMachine and its strengths and weaknesses are shared.

That’s why you should know this pattern well. Learning the frequent mistakes that people make using it and how to avoid them is something any developer using EventMachine should read about.

Blocking the reactor

Web applications are I/O heavy. Receiving requests and returning responses is reading-from and writing-into sockets. That’s pure input and output operations. We may think that web applications are a good fit for reactor based libraries and frameworks, right? The answer, like in almost any software problem, is it depends.

It is true that asynchronous operations will make the reactor shine. The reactor thread doesn’t block waiting for requests to come. The operating system will notify when there is information available. In the meantime the application can be serving other requests. The same thing will happen handling responses: the write operation will be executed asynchronously without blocking the thread. It’s concurrency paradise!

While it is true that receiving requests and sending responses will greatly benefit of the use of EventMachine we also need to consider what happens in between. If the responses are generated really fast, we truly are in concurrency paradise. We are in front the kind of software that truly fits the reactor pattern. But what happens if the application needs to perform some long running task before generating the response?

In the previous section we discussed how event demultiplexing works in EventMachine’s reactor. Let’s apply that knowledge to the processing of an HTTP request. When a socket has received the HTTP request information and it’s ready to be read, the reactor will be notified by the operating system and it will dispatch the corresponding callback to process it. The callback will be invoked immediately. And, what’s more important, synchronously. It takes control of the reactor’s thread and the event loop will be blocked until the callback execution is over.

You may not see the implications blocking the reactor right now. Let’s put an example so you can experiment them:

EM.run do
  EM.add_periodic_timer(1) { puts 'sec' }
  EM.add_timer(1.01) { puts '1 second passed by' }
  EM.add_timer(2.01) { puts '2 seconds passed by'; }
  EM.add_timer(5.01) do
    puts '5 seconds passed by: stopping...'
    EM.stop
  end
end

We are introducing EM.add_periodic_timer, a new timer flavour that instead of running just once runs indefinitely. Along the periodic timer we are setting up other timers² that should produce the following output:

sec
1 second passed by
sec
2 seconds passed by
sec
sec
5 seconds passed by: stopping...

Every second we will see sec printed out. Along those messages, we will see the specific messages when one and two seconds pass by. Finally, after five seconds, we will see the terminating message and the process will exit.

Now let’s change one of the callbacks. We are going to block the reactor thread when handling the event one second passing by making the process sleep for ten seconds:

EM.run do
  EM.add_periodic_timer(1) { puts 'sec' }
  EM.add_timer(1.01) do
    puts '1 second passed by'
    sleep 10
  end
  EM.add_timer(2.01) { puts '2 seconds passed by'; }
  EM.add_timer(5.01) do
    puts '5 seconds passed by: stopping...'
    EM.stop
  end
end

Lets check what is printed out to standard output:

sec
1 second passed by
sec
2 seconds passed by
5 seconds passed by: stopping...

Wait a second! What’s going on? This process has been running for more than ten seconds. Where are all the missing sec messages? Why didn’t the other output get printed when it was supposed to? EventMachine is broken!

Actually it is not. Let’s review the example to understand what’s going on: The first event that will be triggered will be one second passing by corresponding to the periodic timer. A few reactor ticks later, once ten milliseconds have passed by, the next event will be dispatched. It’s handler will be run and it will execute the sleep 10 sentence. That will block the event loop thread. EventMachine won’t be able to check whether more events have been triggered. For ten seconds the reactor won’t tick at all.

When the process is done sleeping the event loop returns to its usual workflow finishing the previous iteration. In the next one it will start checking if stop has been called. Since the method hasn’t been called yet it will verify if timers have expired. Given that more than ten seconds have gone by since the last check, three callbacks need to be executed: the one corresponding to the periodic timer, the one of the 2 seconds timer and, last, the one of the 5 seconds timer.

Once the timer events have been handled, the reactor will find the call stop and terminate.

In our case blocking the reactor has made us lost three periodic timer events plus delaying another three. There is no I/O involved in this example, but the results would be pretty much the same: no reads or writes would be performed while the event loop is blocked. Sockets ready to be read or written will queue and the throughput of the application would be very poor.

The reactor pattern excels at handling events with callbacks that are dispatched quickly. While a callback is being executed it can’t deal with other events and that’s bad for the performance of any EventMachine powered program.

So, keep it in mind at all times: do NOT block the event loop.

Using synchronous I/O

In the previous example you can tell pretty easily what’s blocking the reactor and why. There are other ways of causing the same issues that are way more subtle. One of the most common ways of doing it and not noticing is using gems that use blocking I/O.

If you use a gem that relies on libraries that are not reactor-aware the I/O operations that you perform won’t be asynchronous. EventMachine won’t handle those sockets or file descriptors and the read and writes from or to them will be blocking. You will be losing all the benefits the reactor pattern provides.

Lets change our previous example a little bit. We are going to remove the sleep and do some blocking I/O operation instead: we are going to get Twitter’s landing page using Ruby standard library’s HTTP capabilities (remember to require net/http). We will do it ten times in order to have the reactor blocked long enough so we can see the effects. We are also going to make our example last a little shorter: three seconds instead of five.

URL = 'http://twitter.com'

EM.run do
  EM.add_periodic_timer(1) { puts 'sec' }
  EM.add_timer(1.01) do
    puts 'one second passed by'
    10.times do
      response = Net::HTTP.get_response(URI.parse(URL))
      puts response.code
    end
  end
  EM.add_timer(2.01) { puts 'two seconds passed by' }
  EM.add_timer(3.01) do
    puts 'three seconds passed by: stopping...'
    EM.stop
  end
end

The results will resemble to the ones we got blocking the loop with sleep:

sec
one second passed by
200
200
200
200
200
200
200
200
200
200
sec
two seconds passed by
three seconds passed by: stopping...

While the requests are done no other event is handled by the reactor. We don’t see the expected sec message when one second passes by, nor is EventMachine stopped after three seconds. We are losing events and making timers malfunction.

Now, let’s swap our blocking HTTP library for an asynchronous one: em-http-request. You will need to install the gem by running:

gem install em-http-request

Then require it in your example code:

require 'em-http'

Look carefully how the one second passing by event handler changes. We are now using non-blocking I/O and that means setting up our response status code output message inside a callback.

EM.run do
  EM.add_periodic_timer(1) { puts 'sec' }
  EM.add_timer(1.01) do
    puts 'one second passed by'
    10.times do
      http = EM::HttpRequest.new(URL).get
      http.callback { puts http.response_header.status }
    end
  end
  EM.add_timer(2.01) { puts 'two seconds passed by' }
  EM.add_timer(3.01) do
    puts 'three seconds passed by: stopping...'
    EM.stop
  end
end

Let’s run this code and analyse the output:

sec
one second passed by
200
200
200
sec
two seconds passed by
200
200
200
200
200
200
sec
three seconds passed by: stopping...

We get the expected three secs. Responses are handled without blocking the reactor and that means that 200 messages are placed among the timer-triggered ones³. Besides that you have experienced how fast asynchronous I/O can be.

You may be wondering how can the performance improvement be so dramatic.

Every time we are calling a get on an EM::HttpRequest instance we are adding a socket to the resources handled by the reactor. Once done the event loop keeps ticking. Those connections will be handled within it. On every tick the reactor will poll those resources and trigger the corresponding callback if responses came back.

On the other hand, when we use net/http, every call to get_response blocks the thread waiting for the server to respond. It repeats the same process for each one of the ten requests that we are making. The reactor doesn’t have a chance to go through it’s usual event demultiplexing loop during that time. Hence the event loosing and timer events delaying.

That’s why you always have be sure that you are using reactor aware libraries for I/O. Remember: do NOT block the event loop.

Remember: this is an extract of an unfinished e-book. ↩
We are adding a 0.1 to the non-periodic timers so we make sure that sec is printed out prior to the other messages that run almost simultaneously. We think the output is easier to follow that way. Otherwise we cant be sure of the order in which messages would be printed out. ↩
If your network connection is slow three seconds may not be enough for the 10 requests to be responded. In that case you may not get the expected ten 200. You can either increase the timer that will make EventMachine stop. There are better ways to ensure that you get the ten responses before stopping the reactor but we haven’t seen them yet. ↩

A useful shell function

2013-05-31T00:00:00+00:00

In last week’s Ruby Weekly one of the recommended posts was about a gem called Dotenv. This gem allows you to setup the environment variables your rails application needs in order to work on your development environment.

The gem will load the environment variables from .env and .ENV files in the application folder. To do so, you will need to call the gem from your application.

The problem is that the gem is conceived to be used within ruby but environment variables are an OS thing and you may need to solve the same problem when using other platforms or languages.

Probably they have similar libraries to do it. But, you already have all the tools you need: your shell.

Exporting variables

I really like ZSH. And ZSH provides hooks to certain events you can plug functions into.

One of those hooks is chpwd. It will run a function every time you change your working directory. We can make use of it, and write a simple function that checks for .env files in the destination folder and sources it.

To do that we only need to write a little function and bind it to the chpwd hook. That code belongs in my .zshrc file and looks like this:

function set_environment() {
  env_file="$PWD/.env"
  if [ -e $env_file ]; then source $env_file; fi
}
function chpwd() { set_environment; }

I use .env files but the name doesn’t really matter.

Then I create the file and export the environment variables:

export TWITTER_KEY=''
export TWITTER_SECRET=''
export S3_KEY=''
export S3_SECRET=''
export S3_ENDPOINT='s3-eu-west-1.amazonaws.com'

And, as soon as you enter the directory where the .env is placed the variables will be automatically exported and available for your application to read.

There are other uses

But you can do way more than exporting environment variables: you can tailor your shell to the project you are working with.

Recently I started working on a Python project. It’s my first python project and one of my coworkers introduced me to virtualenv.

But, unlike RVM or rbenv, there is no such thing (as far as we know) like .ruby-version files. So, I used a .env file to activate the python virtual environment every time I enter the project’s folder:

source project-virtualenv/bin/activate
alias activate="source project-virtualenv/bin/activate"

I also used it to create an alias that allows me to have the opposite command to the deactivate one provided by virtualenv (just in case I deactivate the environment by hand).

As you see the possibilities are enormous. There are a lot of things you can do. Hope you find it as useful as I do!

Starting with EventMachine III

2013-04-07T00:00:00+00:00

You can find all posts here:

Just enough about patterns

In the hello world example we talked about something called the event loop. The event loop is one of the two patterns EventMachine is powered by. Although you could use the library without really knowing anything about this patterns, understanding how they work will make a huge difference. There are certain features and bad practices that wouldn’t make sense otherwise.

We are going to overview both patterns but it’s going to be a really brief introduction. Later in the book we will develop our own reactor and event loop to get a better grasp of their internals.

The reactor

The reactor is an event handling pattern designed to manage service requests that are delivered concurrently to an application. It was conceived with the C10K problem in mind.

The reactor has to be aware of the different service requests or events it will be watching for and their corresponding handlers or callbacks. Those events will come through a set of resources or handles. In EventMachine the handles will be I/O resources like sockets or file descriptors.

Once initialized, the reactor will enter a phase known as event demultiplexing phase. During this stage it will poll the resources for a very sort time span waiting for events to happen. Once an event is triggered in one of the handles, the registered callback for that event, in that particular resource, will be dispatched.

With this newly acquired knowledge we can rephrase what the EM.run method does: it boots EventMachine’s reactor taking a block that will be yielded right before it enters the event demultiplexing phase. That is, prior to starting the event loop.

The event loop

The event loop is EventMachine’s reactor’s event demultiplexer.

When the reactor enters this phase it gets trapped in a loop¹. Each of the iterations through this loop is known as a reactor tick or just tick. During each of them the reactor performs the same three actions:

Check whether enough time has passed by for a timer event to be triggered. It will handle those events by calling the set up callbacks.
Check if any of the handled resources is ready to be read or written and trigger the corresponding event. EventMachine uses the select² system call to poll the handles which is widely available on UNIX and Windows platforms.
Check for dead connections. If an inactivity timeout was set and enough time has passed by without getting any information, the connection will be closed.

Prior to each these three actions EventMachine’s reactor checks whether the stop method has been called. If it wasn’t called the event loop continues otherwise the loop is broken³ and the reactor exits the event demultiplexing phase.

Putting all this together the loop’s pseudocode would look like this:

loop do
  break if stop_was_called?
  trigger_time_based_events

  break if stop_was_called?
  select_handles

  break if stop_was_called?
  close_dead_connections
end

Revisiting the hello world example

That’s all you need to know about the reactor and the event loop right now. Obviously there are a lot of subtleties on how EventMachine works but the basics are covered. This brief explanation will make a huge difference when you try to understand how the library primitives work out.

In fact, it will already pay of. With our current level of understanding of how EventMachine works we can explain the behaviour of the second version of our hello world application. Let me refresh your memory:

EM.run do
  puts "starting EventMachine at \#{format_as_hhmmss(Time.now)}"
  EM.add_timer(0) { puts "Hello world" }
  EM.stop
  puts "stopping EventMachine at \#{format_as_hhmmss(Time.now)}"
end

We got both messages as output even though we were calling EM.stop before printing the second message. We also didn’t get the hello world message despite it should be printed in response to 0 seconds passing by:

starting EventMachine at 17:17:37
stopping EventMachine at 17:17:37

Lets think carefully on what’s going on. All the code we have is inside the block we are passing to EM.run. That means it will be executed before the reactor enters the event demultiplexing phase. Before the event loop is started both messages will be printed, an event handler for the event 0 seconds passing by is set up and EM.stop is called.

When the loop starts, the first thing the reactor will do is checking if stop has been called, even before checking if there are timer events to be triggered. It will find that the stop has been scheduled and break the loop immediately. The reactor will check the timers not even once.

Quite literally because it uses Ruby’s loop construct ↩
Latest versions of EventMachine can also use a better mechanism where available called epoll ↩
Again, literally calling break ↩

Starting with EventMachine II

2013-03-25T00:00:00+00:00

You can find all posts here:

Despite being a pretty simple six line example, in the last post you could get the feeling of how building an EventMachine application will be. Evented code has certain characteristics that make it different from the plain old sequential code that we are used to write.

Getting the feeling of evented code

The mind shift

In the procedural world all code is executed in the order it appears in our files.

response1 = Net::HTTP.get_response(uri1)
puts response1.code
puts response1.body

response2 = Net::HTTP.get_response(uri2)
puts response2.code
puts response2.body

response3 = Net::HTTP.get_response(uri3)
puts response3.code
puts response3.body

This code will first perform the first HTTP request. Once the response comes back it will print out the status code and, once that has been printed, it will output the response body. It will repeat this for requests 2 and 3. When this code is run it will follow the exact order the code does.

However, in the land of events that no longer applies. Our code runs in response to things happening.

request1 = EM::MadeUpHTTP.get(uri1)
request1.callback do |response1|
  puts response1.code
  puts response1.body
end

request2 = EM::MadeUpHTTP.get(uri2)
request2.callback do |response2|
  puts response2.code
  puts response2.body
end

request3 = EM::MadeUpHTTP.get(uri3)
request3.callback do |response|
  puts response3.code
  puts response3.body
end

The output of this code can’t be predicted. You won’t know which response will arrive first so you can’t know the order in which callbacks will be run either. The responses can arrive in any order. It can be response1 the one that comes first but it could also be response2 or response3. It has nothing to do with the flow of the code nor the order in which the requests were made. The callbacks will be executed asynchronously. The only thing that remains synchronous is the execution of the code inside the callbacks. That’s the only place where the rules of the procedural world still apply.

It will require a mind shift but you will need to start structuring your code around responding to events instead of around performing a sequence of actions. The flow of the program depends on the flow of events not on the flow of the code.

You will also need to understand the ecosystem where your code is running: check out this alternate version of the hello world example. It uses the same constructs as the previous one with minor changes: the EM.stop call has been taken out of the timer callback and we are now handing the event zero seconds passing by.

EM.run do
  puts "starting EventMachine at \#{format_as_hhmmss(Time.now)}"
  EM.add_timer(0) { puts "Hello world" }
  EM.stop
  puts "stopping EventMachine at \#{format_as_hhmmss(Time.now)}"
end

Even if the call to the EM.add_timer method appears before the one to EM.stop, and even if we are waiting for 0 seconds to pass by, the code in the callback will never be executed. You will also see the second message even if we are stopping EventMachine in the previous line:

starting EventMachine at 17:17:37
stopping EventMachine at 17:17:37

In this case we are not letting the event loop start handling events: we are stopping it right in the setup phase. This is the reason why we were calling EM.stop inside the callback in the first example: to make sure that EventMachine waits for the event to be triggered and handled.

Block nightmare

EventMachine relies heavily on Ruby blocks for callback setting. Most of the times callbacks trigger new events that will also need to be handled. That means that we can end up with a lot of block nesting and that can make the code really hard to understand.

Let’s take what a web application usually does as an example: it will receive a request through a certain route, get some information out of the database and render some HTML that will be returned in the response.

Let’s shape that into a made-up EventMachine-based web framework:

EM.run do
  # other routes...
  on_request('/user/:id') do |params|
    query = prepare_query(params)
    query_db(query) do |query_results|
      user = process(query_results)
      render('profile.haml', locals: { user: user }) do |html|
        respond_with status: 200, body: html
      end
    end
  end
  # even more routes...
end

I know what you are thinking: that code smells pretty badly!

If you have read Robert C. Martin’s Clean Code¹ you already know that having more than one indentation level should be avoided. We have four indentation levels in nine lines of code, shaping our program into that horrible pyramid.

Besides that you can easily tell that this code breaks several OO principles. And, to tell you the truth, I don’t think it is object oriented at all.

Of course, evented code does not have to be like this. There are several patterns you can apply to design object oriented EventMachine applications. You can also take advantage of the Proc building capabilities Ruby has to make it look even more like so. And the Ruby fibers that were introduced in 1.9 can also be helpful getting your program’s API to look more synchronous.

Testing

We should test all the code we write. In fact we shouldn’t write any production code without a having failing test² first. If this statement is true in the procedural world it is even more important in the land of events. However, testing event oriented code can be really hard. Could you imagine the test setup that would be required to test our web application example? The amount of stubbing it would require to be run?

But you will find other problems testing EventMachine applications even with code as simple as our hello world example. Let’s give it a try (removing the noise of the start and stop messages):

def evented_hello_world
  EM.run do
    EM.add_timer(2) do
      puts "Hello world"
      EM.stop
    end
  end
end

describe 'evented hello world' do
  it 'prints out hello world after two seconds' do
    start_time = Time.now
    STDOUT.should_receive(:puts).with('Hello world')
    evented_hello_world
    finish_time = Time.now
    (finish_time - start_time).should be_between(1.95, 2.15)
  end
end

Lets run the test:

evented hello world
  prints out hello world after two seconds

Finished in 2.1 seconds
  1 example, 0 failures

This single spec takes more than two seconds to pass. Can you imagine how long it would take to run the test suite of a whole app?³ Imagine an application with a few EM.add_timer(60) and everyone will agree that this kind of testing is a no go… We can do better.

You may be wondering if there are specific tools to test evented applications. There are several gems designed to test EventMachine applications specifically. The thing is that they are not needed. At the end of the day you are writing Ruby code so you should be able to test evented code with the tools you are already familiar with.

Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin) ↩
One of the three laws of Test-Driven Development ↩
Yes, more or less the same it takes a Rails test suite to run. ↩

Starting with EventMachine I

2013-03-13T00:00:00+00:00

You can all the posts here:

What’s EventMachine

What’s EventMachine you may be wondering? EventMachine is an event-driven I/O and lightweight concurrency library for Ruby. It provides an API to handle many different protocols and the ones that are not distributed with it can be found as gems.

Hello evented world

Many blog posts and talks about EventMachine use an echo server and client to show how the library works. Is kind of the hello world version of libraries that deal with concurrency. Even though it’s a great example of how easy it is to create servers and connect to them with EventMachine I don’t think it’s a good way of getting started.

We are going to start simple. Our first program will be the closest it can get to the usual hello world but with an evented flavour. We will:

Start EventMachine.
Create a time based event that will trigger after 2 seconds.
Create a callback that handles that event which will print the message “Hello world” and stop EventMachine.

The first thing you need to do to get started is installing EventMachine. This one will be easy. It’s distributed as a gem so you can install it by running:

gem install eventmachine

You will need to require it in order to use it in your program:

require 'eventmachine'

Once you have done that you are set to write your first EventMachine powered application: an event powered hello world! (the time formatting has been omitted for simplicity):

EventMachine.run do
  puts "starting EventMachine at \#{format_as_hhmmss(Time.now)}"
  EM.add_timer(2) do
    puts "Hello world"
    puts "stopping EventMachine at \#{format_as_hhmmss(Time.now)}"
    EM.stop
  end
end

You may have noticed that I have used both EventMachine and EM. In the library codebase you can find this line:

EM = EventMachine

Both modules are the same thing. EM is just an alias created for convenience so we don’t need to type the whole name every single time.

When you run this code the first thing you will see will be the time EventMachine was started at. Two seconds later the Hello world will be printed out and, almost simultaneously, the stopping message:

starting EventMachine at 10:35:56
Hello world
stopping EventMachine at 10:35:58

What does `EM.run` do?

The method run starts EventMachine’s event loop. Don’t worry if you have no idea of what an event loop is: you you will by the end of this chapter. Once started it traps the thread it runs in, so the code won’t continue running until it’s stopped. For now you can think of it being a while(true) loop.

EM.run takes a block. The block will be yielded right before the event loop is booted. That means this is the place to setup everything your application may need.

What does `EM.stop` do?

As you may have figured out, the stop method halts the event loop and returns the control to the thread that started it.

Calling this method will stop EventMachine almost immediately (we will learn what almost immediately means when we dig deeper into how the event loop works). It will wait for no event to be triggered and no callback to be run. That means we need to be careful with when and how we stop EventMachine.

What does `EM.add_timer` do?

By calling this method you are setting up your first event handler or callback. You are telling EventMachine to watch for an event: two seconds passing by. Once that event is triggered (once two seconds pass by), EventMachine will run the block you passed to EM.add_timer.

Here is where you can see the Hollywood Principle applied. Usually you call other application’s code. Whether they are gems, frameworks or APIs it is your code who calls them. In this case it will be the other way around: the library will be the one calling the code you wrote. It’s a very common pattern to deal with asynchrony.

Internal vs. External DSL

2012-01-23T00:00:00+00:00

For those of you who have never heard about it, DSL stands for Domain Specific Language. Basically it’s a language which is built for a specific domain (hence the name). They are pretty common in the computer world, and you may be using a few without even knowing it.

Domain-specific language: a computer programming language of limited expressiveness focused on a particular domain.

RSpec or Rake Rake are clear examples of DSLs. They use all the power of the Ruby language to make you feel like using a language that was designed with a particular problem in mind.

This kind of DSL that bends and twists a host language to make it feel like a different one is known as Internal DSL and is the only kind of DSL I was aware of.

My current apprentice task involves building a DSL that is 100% in Spanish. Ruby is so flexible that you can do such a thing. But I also have very strong syntax constraints. That’s why I have been struggling for a long time trying to build it an Internal DSL to solve this particular problem.

Today (after my mentor asked me to write this post) I have learned that there is another type of Domain-specific Languages: the external ones.

It turns out that Cucumber is an external DSL. But also CSS, Sass and many other technologies that I would have never considered a Domain Specific Language, are such a thing.

External DSLs have their own syntax instead of being built on top of a language. All you need to make it work is a parser that interprets the language or that translates it to another one.

This post by Martin Fowler has been really helpful to understand the whole thing. Now I know how to complete my task.

Javier Acero

Consistent Design

Tackling the median complexity

Advantages

Problems

Over-engineering

Under-engineering

The price of consistency

A better approach to consistency

Interesting content (January 2018)

Talks

The art of destroying software by Greg Young

Books

Posts

Auto-squashing git commits by Thought Bot

Stop abusing NotImplementedError

The modern dev team

Don’t cross the beams by Kent Beck

Interesting content (December 2017)

Talks

The “right” way to ship software

Evolutionary architectures

Books

Clean Architecture (Uncle Bob)

The Nature of Software Development (Ron Jeffries)

Posts

Managing your personal tech portfolio

Excuses by Uncle bob.

Elixir code quality tools by Matt Gauger

The smell of that potion

Starting with EventMachine IV

Doing it the wrong way

Blocking the reactor

Using synchronous I/O

A useful shell function

Exporting variables

There are other uses

Starting with EventMachine III

Just enough about patterns

The reactor

The event loop

Revisiting the hello world example

Starting with EventMachine II

Getting the feeling of evented code

The mind shift

Block nightmare

Testing

Starting with EventMachine I

What’s EventMachine

Hello evented world

What does EM.run do?

What does EM.stop do?

What does EM.add_timer do?

Internal vs. External DSL

What does `EM.run` do?

What does `EM.stop` do?

What does `EM.add_timer` do?