Class: Orocos::Port

Inherits:
Object
  • Object
show all
Includes:
PortBase
Defined in:
lib/orocos/ports.rb,
lib/orocos/ros/ports.rb

Overview

Base class for port classes.

See OutputPort and InputPort

Direct Known Subclasses

InputPort, OutputPort

Constant Summary collapse

DEFAULT_CONNECTION_POLICY =
{
    :type => :data,
    :init => false,
    :pull => false,
    :data_size => 0,
    :size => 0,
    :lock => :lock_free,
    :transport => 0,
    :name_id => ""
}
CONNECTION_POLICY_OPTIONS =
DEFAULT_CONNECTION_POLICY.keys
@@transient_port_id_counter =
0

Class Attribute Summary collapse

Attributes included from PortBase

#model, #name, #orocos_type_name, #task, #type

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PortBase

#==, #ensure_type_available, #full_name, #initialize, #log_metadata, #max_marshalling_size, #max_sizes, #new_sample, #to_s

Class Attribute Details

.transport_namesObject (readonly)

A mapping from a transport ID to its name in plain text


35
36
37
# File 'lib/orocos/ports.rb', line 35

def transport_names
  @transport_names
end

Class Method Details

.prepare_policy(policy = Hash.new) ⇒ Object

fills missing policy fields with default values, checks if the generated policy is valid and returns it


125
126
127
128
# File 'lib/orocos/ports.rb', line 125

def self.prepare_policy(policy = Hash.new)
    policy = DEFAULT_CONNECTION_POLICY.merge policy
    Port.validate_policy(policy)
end

.transient_local_port_name(base_name) ⇒ Object


28
29
30
# File 'lib/orocos/ports.rb', line 28

def self.transient_local_port_name(base_name)
    "#{base_name}.#{@@transient_port_id_counter += 1}"
end

.transport_name(id) ⇒ Object

Returns the transport name for the given transport ID or a placeholder sentence if no name is known for this transport ID


40
41
42
# File 'lib/orocos/ports.rb', line 40

def self.transport_name(id)
    transport_names[id] || "unknown transport with ID #{id}"
end

.validate_policy(policy) ⇒ Object

A connection policy is represented by a hash whose elements are each of the policy parameters. Valid policies are:

  • buffer policy. Values are stored in a FIFO of the specified size. Connecting with a buffer policy is done with:

    output_port.connect_to(input_port, :type => :buffer, :size => 10)
    
  • data policy. The input port will always read the last value pushed by the output port. It is the default policy, but can be explicitly specified with:

    output_port.connect_to(input_port, :type => :data)
    

An additional :pull option specifies if samples should be pushed by the output end (i.e. if all samples that are written on the output port are sent to the input port), or if the values are transmitted only when the input port is read. For instance:

output_port.connect_to(input_port, :type => :data, :pull => true)

Finally, the type of locking can be specified. The lock_free locking policy guarantees that a high-priority thread will not be “taken over” by a low-priority one, but requires a lot of copying – so avoid it in non-hard-realtime contexts with big data samples. The locked locking policy uses mutexes, so is not ideal in hard realtime contexts. Each policy is specified with:

output_port.connect_to(input_port, :lock => :lock_free)
output_port.connect_to(input_port, :lock => :locked)

This method raises ArgumentError if the policy is not valid.


106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# File 'lib/orocos/ports.rb', line 106

def self.validate_policy(policy)
    policy = validate_options policy, CONNECTION_POLICY_OPTIONS
    if policy.has_key?(:type)
        policy[:type] = policy[:type].to_sym
    end
    if policy.has_key?(:lock)
        policy[:lock] = policy[:lock].to_sym
    end

    if policy[:type] == :buffer && !policy[:size]
        raise ArgumentError, "you must provide a 'size' argument for buffer connections"
    elsif policy[:type] == :data && (policy[:size] && policy[:size] != 0)
        raise ArgumentError, "there are no 'size' argument to data connections"
    end
    policy
end

Instance Method Details

#create_stream(transport, name_id, policy = Hash.new) ⇒ Object

Publishes or subscribes this port on a stream


150
151
152
153
154
155
156
157
158
159
# File 'lib/orocos/ports.rb', line 150

def create_stream(transport, name_id, policy = Hash.new)
    policy = Port.prepare_policy(policy)
    policy[:transport] = transport
    policy[:name_id] = name_id
    do_create_stream(policy)
            
    self
rescue Orocos::ConnectionFailed => e
    raise e, "failed to create stream from #{full_name} on transport #{Port.transport_name(transport)}, name #{name_id} and policy #{policy.inspect}"
end

#default_ros_topic_nameObject


3
4
5
# File 'lib/orocos/ros/ports.rb', line 3

def default_ros_topic_name
    "#{task.name}/#{self.name}"
end

#disconnect_allObject

Removes this port from all connections it is part of


57
58
59
60
61
# File 'lib/orocos/ports.rb', line 57

def disconnect_all
    refine_exceptions do
        do_disconnect_all
    end
end

#docObject

Returns a documentation string describing the port If no documentation is available it returns nil


138
139
140
141
142
# File 'lib/orocos/ports.rb', line 138

def doc
    if model
        model.doc
    end
end

#doc?Boolean

Returns true if a documentation about the port is available otherwise it retuns false


132
133
134
# File 'lib/orocos/ports.rb', line 132

def doc?
    (doc && !doc.empty?)
end

#pretty_print(pp) ⇒ Object

:nodoc:


48
49
50
51
52
53
54
# File 'lib/orocos/ports.rb', line 48

def pretty_print(pp) # :nodoc:
    if type.name != orocos_type_name
        pp.text " #{name} (#{type.name}/#{orocos_type_name})"
    else
        pp.text " #{name} (#{type.name})"
    end
end

#remove_stream(name_id) ⇒ Object

Removes a stream publication. The name should be the same than the one given to the


163
164
165
166
# File 'lib/orocos/ports.rb', line 163

def remove_stream(name_id)
    do_remove_stream(name_id)
    self
end

#to_orocos_portObject

Returns the Orocos port


145
146
147
# File 'lib/orocos/ports.rb', line 145

def to_orocos_port
    self
end

#type_nameObject

Deprecated.

Returns the name of the typelib type. Use #type.name instead.


46
# File 'lib/orocos/ports.rb', line 46

def type_name; type.name end