README.md.in

# Einhorn: the language-independent shared socket manager

![Einhorn](https://stripe.com/img/blog/posts/meet-einhorn/einhorn.png)

Let's say you have a server process which processes one request at a
time. Your site is becoming increasingly popular, and this one process
is no longer able to handle all of your inbound connections. However,
you notice that your box's load number is low.

So you start thinking about how to handle more requests. You could
rewrite your server to use threads, but threads are a pain to program
against (and maybe you're writing in Python or Ruby where you don't
have true threads anyway). You could rewrite your server to be
event-driven, but that'd require a ton of effort, and it wouldn't help
you go beyond one core. So instead, you decide to just run multiple
copies of your server process.

Enter Einhorn. Einhorn makes it easy to run (and keep alive) multiple
copies of a single long-lived process. If that process is a server
listening on some socket, Einhorn will open the socket in the master
process so that it's shared among the workers.

Einhorn is designed to be compatible with arbitrary languages and
frameworks, requiring minimal modification of your
application. Einhorn is simple to configure and run.

## Installation

Install from Rubygems as:

    $ gem install einhorn

Or build from source by:

    $ gem build einhorn.gemspec

And then install the built gem.

[[usage]]

## Contributing

Contributions are definitely welcome. To contribute, just follow the
usual workflow:

1. Fork Einhorn
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Github pull request

## History

Einhorn came about when Stripe was investigating seamless code
upgrading solutions for our API worker processes. We really liked the
process model of [Unicorn](http://unicorn.bogomips.org/), but didn't
want to use its HTTP functionality. So Einhorn was born, providing the
master process functionality of Unicorn (and similar preforking
servers) to a wider array of applications.

See https://stripe.com/blog/meet-einhorn for more background.

Stripe currently uses Einhorn in production for a number of
services. You can use Conrad Irwin's thin-attach_socket gem along with
EventMachine-LE to support file-descriptor passing. Check out
`example/thin_example` for an example of running Thin under Einhorn.

## Compatibility

Einhorn runs in Ruby 2.0, 2.1, and 2.2

The following libraries ease integration with Einhorn with languages other than
Ruby:

- **[go-einhorn](https://github.com/stripe/go-einhorn)**: Stripe's own library
  for *talking* to an einhorn master (doesn't wrap socket code).
- **[goji](https://github.com/zenazn/goji/)**: Go (golang) server framework. The
  [`bind`](https://godoc.org/github.com/zenazn/goji/bind) and
  [`graceful`](https://godoc.org/github.com/zenazn/goji/graceful)
  packages provide helpers and HTTP/TCP connection wrappers for Einhorn
  integration.
- **[github.com/CHH/einhorn](https://github.com/CHH/einhorn)**: PHP library
- **[thin-attach\_socket](https://github.com/ConradIrwin/thin-attach_socket)**:
  run `thin` behind Einhorn
- **[baseplate](https://reddit.github.io/baseplate/cli/serve.html)**: a
  collection of Python helpers and libraries, with support for running behind
  Einhorn

*NB: this list should not imply any official endorsement or vetting!*

## About

Einhorn is a project of [Stripe](https://stripe.com), led by [Carl Jackson](https://github.com/zenazn). Feel free to get in touch at
info@stripe.com.