google-cloud-pubsub 0.27.1 → 0.27.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d86a72ae11e23498af47c4a4137eb6ecd9382df9
-  data.tar.gz: e34a6d21a79b06b387193d17d087405e8c995cf2
+  metadata.gz: f83c458e0a45afd77106e7e66922ad2b1e1d8515
+  data.tar.gz: 6aeda54db32d7f78e6c8b649cad9beac294408d4
 SHA512:
-  metadata.gz: c88a3987a5bac8329cbf89dde504a3c7f74a52f5ad2d0e0557bf9bff83e57dc869965f90b03829f66de54031b5693a52a9c6ceb0a8a24fb2f7d85d9ed9767c75
-  data.tar.gz: e03c8e11e8a5f30c738e3fd3a1ca97d99407a6ea6fcba7c1dba206763164ec2f11c83f5e48cfd79de7af0ebdacccd6f25ef8dff55609d0099a7f06d4d6cd1bd8
+  metadata.gz: 609784712397870174e5fd07a41978f74616ee7bab81db6ad007efda11b8bb2d1d13f8dce68e0681f1ff4e64be8d2b5c5035e8ae8a10e0a669776eda474430d1
+  data.tar.gz: af8a25738680f2d7fb74e236ecb6ce7db9a7b5de56774fc34d33f917464c251c13caec9f4cc4d96750a1db786a8a424fd92064dd5b379278820f2d73222f432f

data/README.md

@@ -37,8 +37,17 @@ msg = topic.publish "new-message"
 # Retrieve a subscription
 sub = pubsub.subscription "my-topic-sub"
 
-# Pull available messages
-msgs = sub.pull
+# Create a subscriber to listen for available messages
+subscriber = sub.listen do |received_message|
+  # process message
+  received_message.acknowledge!
+end
+
+# Start background threads that will call the block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop.wait!
 ```
 
 ## Supported Ruby Versions

data/lib/google/cloud/pubsub.rb

@@ -185,10 +185,12 @@ module Google
     # end
     # ```
     #
-    # ## Pulling Messages
+    # ## Receiving messages
     #
-    # Messages are pulled from a Subscription. (See
-    # {Google::Cloud::Pubsub::Subscription#pull})
+    # Messages can be streamed from a subscription with a subscriber object
+    # that is created using `listen`. (See
+    # {Google::Cloud::Pubsub::Subscription#listen} and
+    # {Google::Cloud::Pubsub::Subscriber})
     #
     # ```ruby
     # require "google/cloud/pubsub"
@@ -196,22 +198,21 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # sub = pubsub.subscription "my-topic-sub"
-    # msgs = sub.pull
-    # ```
-    #
-    # A maximum number of messages returned can also be specified:
     #
-    # ```ruby
-    # require "google/cloud/pubsub"
+    # subscriber = sub.listen do |received_message|
+    #   # process message
+    #   received_message.acknowledge!
+    # end
     #
-    # pubsub = Google::Cloud::Pubsub.new
+    # # Start background threads that will call the block passed to listen.
+    # subscriber.start
     #
-    # sub = pubsub.subscription "my-topic-sub", max: 10
-    # msgs = sub.pull
+    # # Shut down the subscriber when ready to stop receiving messages.
+    # subscriber.stop.wait!
     # ```
     #
-    # The request for messages can also block until messages are available.
-    # (See {Google::Cloud::Pubsub::Subscription#wait_for_messages})
+    # Messages also can be pulled directly in a one-time operation. (See
+    # {Google::Cloud::Pubsub::Subscription#pull})
     #
     # ```ruby
     # require "google/cloud/pubsub"
@@ -219,13 +220,10 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # sub = pubsub.subscription "my-topic-sub"
-    # msgs = sub.wait_for_messages
+    # received_messages = sub.pull
     # ```
     #
-    # Messages can also be streamed from a subscription with a subscriber object
-    # that can be created using `listen`. (See
-    # {Google::Cloud::Pubsub::Subscription#listen} and
-    # {Google::Cloud::Pubsub::Subscriber})
+    # A maximum number of messages to pull can be specified:
     #
     # ```ruby
     # require "google/cloud/pubsub"
@@ -233,16 +231,7 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # sub = pubsub.subscription "my-topic-sub"
-    #
-    # subscriber = sub.listen do |msg|
-    #   # process msg
-    #   msg.ack!
-    # end
-    #
-    # subscriber.start
-    #
-    # # Shut down the subscriber when ready to stop receiving messages.
-    # subscriber.stop.wait!
+    # received_messages = sub.pull max: 10
     # ```
     #
     # ## Acknowledging a Message
@@ -260,7 +249,17 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # sub = pubsub.subscription "my-topic-sub"
-    # sub.pull.each { |msg| msg.acknowledge! }
+    #
+    # subscriber = sub.listen do |received_message|
+    #   # process message
+    #   received_message.acknowledge!
+    # end
+    #
+    # # Start background threads that will call the block passed to listen.
+    # subscriber.start
+    #
+    # # Shut down the subscriber when ready to stop receiving messages.
+    # subscriber.stop.wait!
     # ```
     #
     # Or, multiple messages can be acknowledged in a single API call:
@@ -290,12 +289,18 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # sub = pubsub.subscription "my-topic-sub"
-    # received_message = sub.pull.first
-    # if received_message
+    # subscriber = sub.listen do |received_message|
     #   puts received_message.message.data
+    #
     #   # Delay for 2 minutes
     #   received_message.delay! 120
     # end
+    #
+    # # Start background threads that will call the block passed to listen.
+    # subscriber.start
+    #
+    # # Shut down the subscriber when ready to stop receiving messages.
+    # subscriber.stop.wait!
     # ```
     #
     # The message can also be made available for immediate redelivery:
@@ -306,12 +311,18 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # sub = pubsub.subscription "my-topic-sub"
-    # received_message = sub.pull.first
-    # if received_message
+    # subscriber = sub.listen do |received_message|
     #   puts received_message.message.data
-    #   # Mark for redelivery by setting the deadline to now
-    #   received_message.delay! 0
+    #
+    #   # Mark for redelivery
+    #   received_message.reject!
     # end
+    #
+    # # Start background threads that will call the block passed to listen.
+    # subscriber.start
+    #
+    # # Shut down the subscriber when ready to stop receiving messages.
+    # subscriber.stop.wait!
     # ```
     #
     # Multiple messages can be delayed or made available for immediate
@@ -349,8 +360,8 @@ module Google
     #
     # snapshot = sub.create_snapshot
     #
-    # messages = sub.pull
-    # sub.acknowledge messages
+    # received_messages = sub.pull
+    # sub.acknowledge received_messages
     #
     # sub.seek snapshot
     # ```
@@ -369,11 +380,12 @@ module Google
     #
     # sub = pubsub.subscription "my-topic-sub"
     #
-    # subscriber = sub.listen do |msg|
-    #   # process msg
-    #   msg.ack!
+    # subscriber = sub.listen do |received_message|
+    #   # process message
+    #   received_message.acknowledge!
     # end
     #
+    # # Start background threads that will call the block passed to listen.
     # subscriber.start
     #
     # # Shut down the subscriber when ready to stop receiving messages.
@@ -392,12 +404,13 @@ module Google
     #
     # sub = pubsub.subscription "my-topic-sub"
     #
-    # subscriber = sub.listen threads: { callback: 16 } do |msg|
+    # subscriber = sub.listen threads: { callback: 16 } do |received_message|
     #   # store the message somewhere before acknowledging
-    #   store_in_backend msg.data # takes a few seconds
-    #   msg.ack!
+    #   store_in_backend received_message.data # takes a few seconds
+    #   received_message.acknowledge!
     # end
     #
+    # # Start background threads that will call the block passed to listen.
     # subscriber.start
     # ```
     #

data/lib/google/cloud/pubsub/message.rb

@@ -39,10 +39,18 @@ module Google
       #   message = topic.publish "task completed"
       #   message.data #=> "task completed"
       #
-      #   # Pull a message
+      #   # Listen for messages
       #   sub = pubsub.subscription "my-topic-sub"
-      #   received_message = sub.pull.first
-      #   received_message.message.data #=> "task completed"
+      #   subscriber = sub.listen do |received_message|
+      #     # process message
+      #     received_message.acknowledge!
+      #   end
+      #
+      #   # Start background threads that will call the block passed to listen.
+      #   subscriber.start
+      #
+      #   # Shut down the subscriber when ready to stop receiving messages.
+      #   subscriber.stop.wait!
       #
       class Message
         ##

data/lib/google/cloud/pubsub/received_message.rb

@@ -30,12 +30,17 @@ module Google
       #   pubsub = Google::Cloud::Pubsub.new
       #
       #   sub = pubsub.subscription "my-topic-sub"
-      #   received_message = sub.pull.first
-      #   if received_message
+      #   subscriber = sub.listen do |received_message|
       #     puts received_message.message.data
       #     received_message.acknowledge!
       #   end
       #
+      #   # Start background threads that will call the block passed to listen.
+      #   subscriber.start
+      #
+      #   # Shut down the subscriber when ready to stop receiving messages.
+      #   subscriber.stop.wait!
+      #
       class ReceivedMessage
         ##
         # @private The {Subscription} object.
@@ -102,12 +107,18 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   received_message = sub.pull.first
-        #   if received_message
+        #   subscriber = sub.listen do |received_message|
         #     puts received_message.message.data
+        #
         #     received_message.acknowledge!
         #   end
         #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop.wait!
+        #
         def acknowledge!
           ensure_subscription!
           subscription.acknowledge ack_id
@@ -132,13 +143,19 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   received_message = sub.pull.first
-        #   if received_message
+        #   subscriber = sub.listen do |received_message|
         #     puts received_message.message.data
+        #
         #     # Delay for 2 minutes
         #     received_message.delay! 120
         #   end
         #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop.wait!
+        #
         def delay! new_deadline
           ensure_subscription!
           subscription.delay new_deadline, ack_id
@@ -157,13 +174,19 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   received_message = sub.pull.first
-        #   if received_message
+        #   subscriber = sub.listen do |received_message|
         #     puts received_message.message.data
+        #
         #     # Release message back to the API.
         #     received_message.reject!
         #   end
         #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop.wait!
+        #
         def reject!
           delay! 0
         end

data/lib/google/cloud/pubsub/subscriber.rb

@@ -31,11 +31,12 @@ module Google
       #
       #   sub = pubsub.subscription "my-topic-sub"
       #
-      #   subscriber = sub.listen do |msg|
-      #     # process msg
-      #     msg.ack!
+      #   subscriber = sub.listen do |received_message|
+      #     # process message
+      #     received_message.acknowledge!
       #   end
       #
+      #   # Start background threads that will call the block passed to listen.
       #   subscriber.start
       #
       #   # Shut down the subscriber when ready to stop receiving messages.

data/lib/google/cloud/pubsub/subscription.rb

@@ -35,8 +35,16 @@ module Google
       #   pubsub = Google::Cloud::Pubsub.new
       #
       #   sub = pubsub.subscription "my-topic-sub"
-      #   msgs = sub.pull
-      #   msgs.each { |msg| msg.acknowledge! }
+      #   subscriber = sub.listen do |received_message|
+      #     # process message
+      #     received_message.acknowledge!
+      #   end
+      #
+      #   # Start background threads that will call the block passed to listen.
+      #   subscriber.start
+      #
+      #   # Shut down the subscriber when ready to stop receiving messages.
+      #   subscriber.stop.wait!
       #
       class Subscription
         ##
@@ -231,11 +239,17 @@ module Google
         # `UNAVAILABLE` if there are too many concurrent pull requests pending
         # for the given subscription.
         #
+        # See also {#listen} for the preferred way to process messages as they
+        # become available.
+        #
         # @param [Boolean] immediate When `true` the system will respond
         #   immediately even if it is not able to return messages. When `false`
         #   the system is allowed to wait until it can return least one message.
         #   No messages are returned when a request times out. The default value
         #   is `true`.
+        #
+        #   See also {#listen} for the preferred way to process messages as they
+        #   become available.
         # @param [Integer] max The maximum number of messages to return for this
         #   request. The Pub/Sub system may return fewer than the number
         #   specified. The default value is `100`, the maximum value is `1000`.
@@ -248,7 +262,7 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   sub.pull.each { |msg| msg.acknowledge! }
+        #   sub.pull.each { |received_message| received_message.acknowledge! }
         #
         # @example A maximum number of messages returned can also be specified:
         #   require "google/cloud/pubsub"
@@ -256,7 +270,9 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   sub.pull(max: 10).each { |msg| msg.acknowledge! }
+        #   sub.pull(max: 10).each do |received_message|
+        #     received_message.acknowledge!
+        #   end
         #
         # @example The call can block until messages are available:
         #   require "google/cloud/pubsub"
@@ -264,8 +280,10 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   msgs = sub.pull immediate: false
-        #   msgs.each { |msg| msg.acknowledge! }
+        #   received_messages = sub.pull immediate: false
+        #   received_messages.each do |received_message|
+        #     received_message.acknowledge!
+        #   end
         #
         def pull immediate: true, max: 100
           ensure_service!
@@ -284,6 +302,9 @@ module Google
         #
         #   subscription.pull immediate: false
         #
+        # See also {#listen} for the preferred way to process messages as they
+        # become available.
+        #
         # @param [Integer] max The maximum number of messages to return for this
         #   request. The Pub/Sub system may return fewer than the number
         #   specified. The default value is `100`, the maximum value is `1000`.
@@ -296,8 +317,10 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   msgs = sub.wait_for_messages
-        #   msgs.each { |msg| msg.acknowledge! }
+        #   received_messages = sub.wait_for_messages
+        #   received_messages.each do |received_message|
+        #     received_message.acknowledge!
+        #   end
         #
         def wait_for_messages max: 100
           pull immediate: false, max: max
@@ -327,8 +350,9 @@ module Google
         #       ({ReceivedMessage#nack!}, {ReceivedMessage#delay!}). Default is
         #       4.
         #
-        # @yield [msg] a block for processing new messages
-        # @yieldparam [ReceivedMessage] msg the newly received message
+        # @yield [received_message] a block for processing new messages
+        # @yieldparam [ReceivedMessage] received_message the newly received
+        #   message
         #
         # @return [Subscriber]
         #
@@ -339,11 +363,12 @@ module Google
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #
-        #   subscriber = sub.listen do |msg|
-        #     # process msg
-        #     msg.ack!
+        #   subscriber = sub.listen do |received_message|
+        #     # process message
+        #     received_message.acknowledge!
         #   end
         #
+        #   # Start background threads that will call block passed to listen.
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
@@ -356,12 +381,13 @@ module Google
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #
-        #   subscriber = sub.listen threads: { callback: 16 } do |msg|
+        #   subscriber = sub.listen threads: { callback: 16 } do |rec_message|
         #     # store the message somewhere before acknowledging
-        #     store_in_backend msg.data # takes a few seconds
-        #     msg.ack!
+        #     store_in_backend rec_message.data # takes a few seconds
+        #     rec_message.acknowledge!
         #   end
         #
+        #   # Start background threads that will call block passed to listen.
         #   subscriber.start
         #
         def listen deadline: nil, streams: nil, inventory: nil, threads: {},
@@ -382,6 +408,8 @@ module Google
         # Acknowledging a message more than once will not result in an error.
         # This is only used for messages received via pull.
         #
+        # See also {ReceivedMessage#acknowledge!}.
+        #
         # @param [ReceivedMessage, String] messages One or more
         #   {ReceivedMessage} objects or ack_id values.
         #
@@ -391,8 +419,8 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   messages = sub.pull
-        #   sub.acknowledge messages
+        #   received_messages = sub.pull
+        #   sub.acknowledge received_messages
         #
         def acknowledge *messages
           ack_ids = coerce_ack_ids messages
@@ -410,6 +438,8 @@ module Google
         # make the messages available for redelivery if the processing was
         # interrupted.
         #
+        # See also {ReceivedMessage#delay!}.
+        #
         # @param [Integer] new_deadline The new ack deadline in seconds from the
         #   time this request is sent to the Pub/Sub system. Must be >= 0. For
         #   example, if the value is `10`, the new ack deadline will expire 10
@@ -424,8 +454,8 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   messages = sub.pull
-        #   sub.delay 120, messages
+        #   received_messages = sub.pull
+        #   sub.delay 120, received_messages
         #
         def delay new_deadline, *messages
           ack_ids = coerce_ack_ids messages
@@ -510,8 +540,8 @@ module Google
         #
         #   snapshot = sub.create_snapshot
         #
-        #   messages = sub.pull
-        #   sub.acknowledge messages
+        #   received_messages = sub.pull
+        #   sub.acknowledge received_messages
         #
         #   sub.seek snapshot
         #
@@ -523,8 +553,8 @@ module Google
         #
         #   time = Time.now
         #
-        #   messages = sub.pull
-        #   sub.acknowledge messages
+        #   received_messages = sub.pull
+        #   sub.acknowledge received_messages
         #
         #   sub.seek time
         #

data/lib/google/cloud/pubsub/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Pubsub
-      VERSION = "0.27.1"
+      VERSION = "0.27.2"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-pubsub
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.27.2
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-11 00:00:00.000000000 Z
+date: 2017-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core