presence.rb in ably-0.6.2

- old
+ new

@@ -1,9 +1,10 @@
 module Ably::Realtime
   # Presence provides access to presence operations and state for the associated Channel
   class Presence
     include Ably::Modules::EventEmitter
+    include Ably::Modules::AsyncWrapper
     extend Ably::Modules::Enum
 
     STATE = ruby_enum('STATE',
       :initialized,
       :entering,
@@ -12,16 +13,19 @@
       :left,
       :failed
     )
     include Ably::Modules::StateEmitter
 
-    # {Ably::Realtime::Channel} this Presence object is assoicated with
+    # {Ably::Realtime::Channel} this Presence object is associated with
+    # @return {Ably::Realtime::Channel}
     attr_reader :channel
 
     # A unique member identifier for this channel client, disambiguating situations where a given
     # client_id is present on multiple connections simultaneously.
-    # TODO: This does not work at present as no ACK is sent from the server with a memberId
+    #
+    # @note TODO: This does not work at present as no ACK is sent from the server with a memberId
+    # @return {String}
     attr_reader :member_id
 
     def initialize(channel)
       @channel       = channel
       @state         = STATE.Initialized
@@ -34,17 +38,20 @@
       setup_event_handlers
     end
 
     # Enter this client into this channel. This client will be added to the presence set
     # and presence subscribers will see an enter message for this client.
+    #
     # @param [Hash,String] options an options Hash to specify client data and/or client ID, or a String with the client data
     # @option options [String] :data      optional data (eg a status message) for this member
     # @option options [String] :client_id the optional id of the client.
     #                                     This option is provided to support connections from server instances that act on behalf of
     #                                     multiple client_ids. In order to be able to enter the channel with this method, the client
     #                                     library must have been instanced either with a key, or with a token bound to the wildcard clientId.
+    #
     # @yield [Ably::Realtime::Presence] On success, will call the block with the {Ably::Realtime::Presence}
+    #
     # @return [Ably::Models::PresenceMessage] Deferrable {Ably::Models::PresenceMessage} that supports both success (callback) and failure (errback) callbacks
     #
     def enter(options = {}, &blk)
       @client_id = options.fetch(:client_id, client_id)
       @data      = options.fetch(:data, data)
@@ -69,10 +76,11 @@
       end
     end
 
     # Leave this client from this channel. This client will be removed from the presence
     # set and presence subscribers will see a leave message for this client.
+    #
     # @param (see Presence#enter)
     # @yield (see Presence#enter)
     # @return (see Presence#enter)
     #
     def leave(options = {}, &blk)
@@ -99,10 +107,11 @@
     end
 
     # Update the presence data for this client. If the client is not already a member of
     # the presence set it will be added, and presence subscribers will see an enter or
     # update message for this client.
+    #
     # @param (see Presence#enter)
     # @yield (see Presence#enter)
     # @return (see Presence#enter)
     #
     def update(options = {}, &blk)
@@ -118,21 +127,29 @@
       end
     end
 
     # Get the presence state for this Channel.
     # Optionally get a member's {Ably::Models::PresenceMessage} state by member_id
+    #
     # @return [Array<Ably::Models::PresenceMessage>, Ably::Models::PresenceMessage] members on the channel
-    def get()
-      members.map { |key, presence| presence }
+    #
+    def get(member_id = nil)
+      if member_id
+        members.find { |key, presence| presence.member_id == member_id }
+      else
+        members.map { |key, presence| presence }
+      end
     end
 
     # Subscribe to presence events on the associated Channel.
     # This implicitly attaches the Channel if it is not already attached.
     #
     # @param action [Ably::Models::PresenceMessage::ACTION] Optional, the state change action to subscribe to. Defaults to all presence actions
     # @yield [Ably::Models::PresenceMessage] For each presence state change event, the block is called
     #
+    # @return [void]
+    #
     def subscribe(action = :all, &blk)
       ensure_channel_attached do
         subscriptions[message_action_key(action)] << blk
       end
     end
@@ -140,10 +157,12 @@
     # Unsubscribe the matching block for presence events on the associated Channel.
     # If a block is not provided, all subscriptions will be unsubscribed
     #
     # @param action [Ably::Models::PresenceMessage::ACTION] Optional, the state change action to subscribe to. Defaults to all presence actions
     #
+    # @return [void]
+    #
     def unsubscribe(action = :all, &blk)
       if message_action_key(action) == :all
         subscriptions.keys
       else
         Array(message_action_key(action))
@@ -156,11 +175,18 @@
 
     # Return the presence messages history for the channel
     #
     # @param (see Ably::Rest::Presence#history)
     # @option options (see Ably::Rest::Presence#history)
-    def history(options = {})
-      rest_presence.history(options)
+    #
+    # @yield [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] An Array of {Ably::Models::PresenceMessage} objects that supports paging (#next_page, #first_page)
+    #
+    # @return [EventMachine::Deferrable]
+    #
+    def history(options = {}, &callback)
+      async_wrap(callback) do
+        rest_presence.history(options.merge(async_blocking_operations: true))
+      end
     end
 
     # @!attribute [r] __incoming_msgbus__
     # @return [Ably::Util::PubSub] Client library internal channel incoming message bus
     # @api private