README.md in propono-1.3.0 vs README.md in propono-1.4.0
- old
+ new
@@ -4,11 +4,11 @@
[](https://gemnasium.com/meducation/propono)
[](https://codeclimate.com/github/meducation/propono)
Propono is a [pub/sub](http://en.wikipedia.org/wiki/Publish-subscribe_pattern) gem built on top of Amazon Web Services (AWS). It uses Simple Notification Service (SNS) and Simple Queue Service (SQS) to seamlessly pass messages throughout your infrastructure.
-It's beautifully simple to use.
+It's beautifully simple to use. [Watch an introduction](https://www.youtube.com/watch?v=ZM3-Gl5DVgM)
```ruby
# On Machine A
Propono.listen_to_queue('some-topic') do |message|
puts "I just received: #{message}"
@@ -16,11 +16,11 @@
# On Machine B
Propono.publish('some-topic', "The Best Message Ever")
# Output on Machine A a second later.
-# - "I just recieved The Best Message Ever"
+# - "I just received The Best Message Ever"
```
## Installation
Add this line to your application's Gemfile:
@@ -37,10 +37,15 @@
```ruby
Propono.config.access_key = "access-key" # From AWS
Propono.config.secret_key = "secret-key" # From AWS
Propono.config.queue_region = "queue-region" # From AWS
+
+# Or use the IAM profile of the machine
+Propono.config.use_iam_profile = true
+Propono.config.queue_region = "queue-region" # From AWS
+
```
You can then start publishing messages easily from anywhere in your codebase.
```ruby
@@ -56,12 +61,22 @@
# ... Do something interesting with the message
end
```
In the background, Propono is automatically setting up a queue using SQS, a notification system using SNS, and gluing them all together for you. But you don't have to worry about any of that.
-**Note for using in Rake tasks and similar:** Propono spawns new threads for messages sent via SNS. If your application ends before the final thread is executed, then the last message might not send. It's therefore advisable to do a `Thread.join` on the thread that is returned from the final call to `publish`.
+**Does it matter what I set my `application_name` to?**
+For a simple publisher and subscriber deployment, no.
+However, the `application_name` has a direct impact on subscriber behaviour when more than one is in play.
+This is because a queue is established for each application_name/topic combination. In practice:
+* subscribers that share the same `application_name` will act as multiple workers on the same queue. Only one will get to process each message.
+* subscribers that have a different `application_name` will each get a copy of a message to process independently i.e. acts as a one-to-many broadcast.
+
+**Note for using in Rake tasks and similar:** Propono spawns new threads for messages sent via SNS. If your application ends before the final thread is executed, then the last message might not send. There are two options to help you here:
+* Pass the `{async: false}` option to Propono.publish. (This was introduced in 1.3.0)
+* Do a `Thread#join` on each thread that is returned from calls to `publish`.
+
### Using TCP for messages
Publishing directly to SNS takes about 15x longer than publishing over a simple TCP connection. It is therefore sometimes favourable to publish to a separate machine listening for TCP messages, which will then proxy them on.
To send messages this way, you need to set up a little extra config:
@@ -122,11 +137,15 @@
The following configuration settings are available:
```
Propono.config do |config|
+ # Use AWS access and secret keys
config.access_key = "An AWS access key"
config.secret_key = "A AWS secret key"
+ # Or use AWS IAM profile of the machine
+ config.use_iam_profile = true
+
config.queue_region = "An AWS queue region"
config.application_name = "A name unique in your network"
config.udp_host = "The host of a machine used for UDP proxying"
config.udp_port = "The port of a machine used for UDP proxying"
config.tcp_host = "The host of a machine used for TCP proxying"