Package rospy :: Package impl :: Module transport

Source Code for Module rospy.impl.transport

  1  # Software License Agreement (BSD License) 
  2  # 
  3  # Copyright (c) 2008, Willow Garage, Inc. 
  4  # All rights reserved. 
  5  # 
  6  # Redistribution and use in source and binary forms, with or without 
  7  # modification, are permitted provided that the following conditions 
  8  # are met: 
  9  # 
 10  #  * Redistributions of source code must retain the above copyright 
 11  #    notice, this list of conditions and the following disclaimer. 
 12  #  * Redistributions in binary form must reproduce the above 
 13  #    copyright notice, this list of conditions and the following 
 14  #    disclaimer in the documentation and/or other materials provided 
 15  #    with the distribution. 
 16  #  * Neither the name of Willow Garage, Inc. nor the names of its 
 17  #    contributors may be used to endorse or promote products derived 
 18  #    from this software without specific prior written permission. 
 19  # 
 20  # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 21  # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 22  # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
 23  # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
 24  # COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
 25  # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
 26  # BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
 27  # LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
 28  # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
 29  # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
 30  # ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 31  # POSSIBILITY OF SUCH DAMAGE. 
 32  # 
 33  # Revision $Id: transport.py 9434 2010-04-28 00:20:16Z kwc $ 
 34  """ 
 35  Base classes for rospy transports 
 36   
 37  These are the base underlying transport implementations, i.e. 
 38  TCP/IP connections, etc... 
 39   
 40  For topic implementations, see L{topics} 
 41  """ 
 42   
 43  import threading 
 44   
 45  # we need ids for the transports so we can send the IDs instead of 
 46  # full connection details 
 47  _transport_id = 0 
 48  _id_lock = threading.Lock() 
49 -def _nextId():
50 global _transport_id 51 try: 52 _id_lock.acquire() 53 _transport_id += 1 54 return _transport_id 55 finally: 56 _id_lock.release()
57 58 INBOUND = 'i' 59 OUTBOUND = 'o' 60 BIDIRECTIONAL = 'b' 61 62 ## Base API of Transport implementations
63 -class Transport(object):
64 transport_type = 'UNKNOWN' 65 66 ## @param self 67 ## @param direction str: INBOUND | OUTBOUND | BIDIRECTIONAL 68 ## @param name str
69 - def __init__(self, direction, name='unnamed'):
70 self.name = name 71 self.direction = direction 72 self.done = False 73 self.cleanup_cb = None 74 self.endpoint_id = '' 75 76 #STATS 77 self.id = _nextId() 78 self.stat_bytes = 0 79 # Number of messages that have passed through this transport 80 self.stat_num_msg = 0
81 82 ## callback function to invoke when this connection is 83 ## closed. Function will be passed this transport as an argument. 84 ## @param self 85 ## @param cleanup_callback fn(Transport): callback for when connection is closed
86 - def set_cleanup_callback(self, cleanup_callback):
87 self.cleanup_cb = cleanup_callback
88 89 ## terminate i/o. Leaf subclasses should override and call this implementation 90 ## @param self
91 - def close(self):
92 self.done = True 93 if self.cleanup_cb: 94 self.cleanup_cb(self)
95 96 ## Write raw data to transport 97 ## @throws TransportInitialiationError could not be initialized 98 ## @throws TransportTerminated no longer open for publishing
99 - def write_data(self, data):
100 raise Exception("not implemented")
101 102 ## Shell class to hold stats about transport that is being killed off. 103 ## This allows the information to stick around but the original Tranport to be gc'd
104 -class DeadTransport(Transport):
105 106 ## @param self 107 ## @param transport str: transport name
108 - def __init__(self, transport):
109 super(DeadTransport, self).__init__( 110 transport.direction, transport.name) 111 self.transport_type = transport.transport_type #class property 112 self.id = transport.id 113 self.stat_bytes = transport.stat_bytes 114 self.stat_num_msg = transport.stat_num_msg 115 self.done = True 116 self.endpoint_id = transport.endpoint_id
117 118 ## ProtocolHandler interface: implements topic communication for a 119 ## particular protocol(s). In order to understand the methods of this 120 ## API, it is important to understand how topic communication is 121 ## established: 122 ## 123 ## When a subscriber is notified of a new topic publisher, it contacts 124 ## the publisher to establish a connection. The subscriber gathers a 125 ## list of supported protocols (e.g. [['TCPROS'], ['MEMMAP']]) from 126 ## its protocol handlers (L{get_supported}) and then passes these to 127 ## the publisher. Each of these protocols is actual a list, 128 ## e.g. ['MPI', LaneWidth, BusSpeed], since a protocol may have 129 ## associated parameters. This is considered the start of the 130 ## 'negotiation phase'. 131 ## 132 ## subscriber -> pub.requestTopic(protocols) 133 ## 134 ## The Publisher selects a protocol from the lists and tells the 135 ## appropriate protocol handler to prepare the outbound connection: 136 ## 137 ## pub.requestTopic() -> pub.protocol_handler.init_publisher(selected_protocol) 138 ## 139 ## The protocol handler will return a new set of parameters 140 ## representing connection parameters, e.g. [TCPROS, address, 141 ## port]. These new parameters are passed back to the subscriber, 142 ## which tells its protocol handler to establish the connection. 143 ## 144 ## subscriber -> subscriber.protocol_handler.create_transport(protocolParams)
145 -class ProtocolHandler(object): #interface
146 147 ## shutdown any resources associated with handling this protocol 148 ## @param self
149 - def shutdown(self):
150 pass
151 152 ## Create a new Transport using the specified \a protocol_params 153 ## returned from the Publisher \a pub_uri. 154 ## @param self 155 ## @param protocol_params [[str, val*]]: parameter list from Publisher. Actual 156 ## contents are protocol-specified. 157 ## @param pub_uri str: publisher API URI 158 ## @param topic str: topic name 159 ## @return int, str, int: code, message, debug
160 - def create_transport(self, topic, pub_uri, protocol_params):
161 raise Exception("interface impl")
162 163 ## @param self 164 ## @param protocol str: protocol name. Must match string identifier used in 165 ## negotiation. 166 ## @return bool: True if this handler supports the specified protocol"""
167 - def supports(self, protocol):
168 return False
169 170 ## This method is called on subscribers and returns the protocol list 171 ## @param self 172 ## @return [[str, val*]]: list of supported protocol params. Each set of protocol params is a 173 ## list where the first element is the string identifier for the protocol.
174 - def get_supported(self):
175 return []
176 177 ## Prepare a transport based on one of the supported protocols 178 ## declared by a Subscriber. Subscribers supply a list of 179 ## supported protocols, of which one is selected by the Publisher 180 ## and passed to init_publisher(). init_publisher is responsible 181 ## for initializing the publisher based on the selection. 182 ## @param self 183 ## @param topic str: name of topic 184 ## @param protocol: selected protocol parameters from the Subscriber. 185 ## @return (int, str, list): (code, statusMessage, params). params 186 ## is protocol specific. These params will be sent to the Subscriber 187 ## so that it can create_transport().
188 - def init_publisher(self, topic, protocol):
189 raise Exception("interface impl") 190