rospy.impl.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 16621 2012-04-06 00:36:58Z 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