+
+ | Method |
+ Description |
+
+
+ | create |
+
+ Accepts hash of attributes and creates object.
+ Note: creation is a non-blocking call and you will be required to wait for a valid state before using resulting object.
+ |
+
+
+ | save |
+ Saves object.
+ Note: not all objects support updating object. |
+
+
+ | persisted? |
+ Returns true if the object has been persisted. |
+
+
+ | destroy |
+
+ Destroys object.
+ Note: this is a non-blocking call and object deletion might not be instantaneous.
+ |
+
+ | reload |
+ Updates object with latest state from service. |
+
+ | ready? |
+ Returns true if object is in a ready state and able to perform actions. This method will raise an exception if object is in an error state. |
+
+
+ | attributes |
+ Returns a hash containing the list of model attributes and values. |
+
+ identity |
+
+ Returns the identity of the object.
+ Note: This might not always be equal to object.id.
+ |
+
+
+ | wait_for |
+ This method periodically reloads model and then yields to specified block until block returns true or a timeout occurs. |
+
+
+
+The remainder of this document details the model abstraction.
+
+## Create Queue
+
+Queues require a unique name. If you try to create a queue with a name that already exists, fog will throw a `Fog::Rackspace::Queues::ServiceError` exception with a 204 status code.
+
+This is is how you would create a queue named demo-queue
+
+ begin
+ queue = service.queues.create :name => 'demo-queue'
+ rescue Fog::Rackspace::Queues::ServiceError => e
+ if e.status_code == 204
+ # duplicate queue exists
+ end
+ end
+
+## Posting a Message to a Queue
+
+Messages can be any type of data, as long as they do not exceed 256 KB in length. Typical message bodies range from simple values, to a chunk of XML, or a list of JSON values. Fog handles the JSON-encoding required to post the message.
+
+You can post a message a mesage to your queue as follows:
+
+ queue.messages.create :body => 'The laces were out!', :ttl => 360
+
+You must supply both a body and a value for `ttl`. The value of `ttl` must be between 60 and 1209600 seconds (one minute to 14 days).
+
+## Listing Messages in a Queue
+
+Messages in a queue can be listed as follows:
+
+ queue.messages
+
+You can change the behavor by setting the follow attributes on the messages colleciton:
+
+Parameter | Default | Effect
+---- | ---- | ----
+**echo** | `true` | When `true`, your own messages are included.
+**include_claimed** | `false` | By default, only unclaimed messages are returned. Pass this as `true` to get all messages, claimed or not.
+**marker** | `nil` | Used for pagination.
+**limit** | `10` | The maximum number of messages to return. Note that you may receive fewer than the specified limit if there aren't that many available messages in the queue.
+
+For example, to include claimed messages you would do the following:
+
+ queue.messages.include_claimed = true
+ queue.messages
+
+## Claiming Messages in a Queue
+
+Claiming messages is how workers processing a queue mark messages as being handled by that worker, avoiding having two workers process the same message.
+
+Messages can be claimed and processed as follows:
+
+ claims = queue.claims.create :ttl => 300, :grace => 100, :limit => 10
+
+An explanation of the parameters of this call follows:
+
+Parameter | Default | Notes
+---- | ---- | ----
+**ttl** | | The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
+**grace** | | The grace attribute specifies the message grace period in seconds. The value of the grace period must be between 60 and 43200 seconds (12 hours). To deal with workers that have stopped responding (for up to 1209600 seconds or 14 days, including claim lifetime), the server extends the lifetime of claimed messages to be at least as long as the lifetime of the claim itself, plus the specified grace period. If a claimed message would normally live longer than the grace period, its expiration is not adjusted.
+**limit** | 10 | The number of messages to claim. The maximum number of messages you may claim at once is 20.
+
+If the claim is successful it will return a `Fog::Rackspace::Queues::Claims` object if there are not any available messages it will return `false`.
+
+You can iterate through the claimed messages as follows:
+
+ claim.messages.each do |message|
+ # process message here
+ message.destroy
+ end
+
+**Note** You will want to call the `destroy` method on the message after processing to insure it is not processed more than once.
+
+## Renewing a Claim
+
+Once a claim has been made, if the TTL and grace period expire, the claim is automatically released and the messages are made available for others to claim. If you have a long-running process and want to ensure that this does not happen in the middle of the process, you should update the claim with one or both of a TTL or grace period. Updating resets the age of the claim, restarting the TTL for the claim. To update a claim, call:
+
+ claim.ttl = 360
+ claim.grace = 360
+ claim.save
+
+## Refreshing a Claim
+
+If you have a `Fog::Rackspace::Queues::claims` object, keep in mind that it is not a live window into the status of the claim; rather, it is a snapshot of the claim at the time the object was created. To refresh it with the latest information, call its `reload` method. This refreshes all of its attributes with the most current status of the claim.
+
+
+## Releasing a Claim
+
+If you have a claim on several messages and must abandon processing of those messages for any reason, you should release the claim so that those messages can be processed by other workers as soon as possible, instead of waiting for the claim's TTL to expire. When you release a claim, the claimed messages are immediately made available in the queue for other workers to claim. To release a claim, call:
+
+ claim.destroy