####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= 
## descriptive title for the tutorial
## title = Subscriber Proxy
## multi-line description to be displayed in search 
## description = A useful way to use a subscriber and it's callback in a similar way to service callbacks with empty requests. 
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for 
## level= BeginnerCategory
## keywords = rocon service
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

== Overview ==

Quite often you just want to tune into a publisher for one message, not a stream. This will often be the case when tuning into a latched publisher (e.g. it may be serving a map). To do that takes several lines of code and gets annoying to repeat.

The `SubscriberProxy` class takes care of that for you with a similar syntax to the existing `ServiceProxy`.

== Example ==

The infamous talker-listener example. The subscriber proxy provides an alternate way of listening to the topic.

{{{#!highlight python
import rocon_utilities

chatter_proxy = rocon_utilities.SubscriberProxy('chatter', String)
print("Heard: %s" % chatter_proxy())
}}}

=== Breakdown ===

The proxy internally constructs a subscriber and callback. When you call the proxy itself, it merely returns the latest data, or if it hasn't received any, waits for the first data to arrive.

=== Timeouts ===

The call function can be made with a timeout to make sure it doesn't hang:

{{{#!highlight python
print("Heard: %s" % chatter_proxy(rospy.Duration(0.5)))
}}}

=== New Data ===

If you aren't interested in the last data that arrived, you can use (timeouts work for this as well):

{{{#!highlight python
print("Heard: %s" % chatter_proxy.wait_for_next(rospy.Duration(0.5)))
}}}

=== One Shot ===

If you don't want to use it more than once, call it with the constructor
and be sure to let it go out of scope so that it doesn't keep processing callbacks internally.

{{{#!highlight python
chatter_proxy = rocon_utilities.SubscriberProxy('chatter', String)()
}}}

## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE