RT Conponent CORBA service/consumer Port. More...

Inheritance diagram for OpenRTM_aist.CorbaPort.CorbaPort:

Classes
class	CorbaConsumerHolder
	The structure to be stored Consumer information. More...

class	CorbaProviderHolder
	The structure to be stored Provider information. More...

class	subscribe
	Subscription mutching functor for Consumer. More...

class	unsubscribe
	Functor to release Consumer's object. More...

Public Member Functions
def	__del__ (self, PortBase=OpenRTM_aist.PortBase)

def	__init__ (self, name)
	Constructor. More...

def	activateInterfaces (self)
	Activate all Port interfaces. More...

def	deactivateInterfaces (self)
	Deactivate all Port interfaces. More...

def	findProvider (self, nv, cons, iorstr)
	Find out a provider corresponding to the consumer from NVList. More...

def	findProviderOld (self, nv, cons, iorstr)
	Find out a provider corresponding to the consumer from NVList. More...

def	init (self, prop)
	Initializing properties. More...

def	publishInterfaces (self, connector_profile)
	Publish information about interfaces. More...

def	registerConsumer (self, instance_name, type_name, consumer)
	Register the consumer. More...

def	registerProvider (self, instance_name, type_name, provider)
	Register the provider. More...

def	releaseObject (self, ior, cons)
	Releasing Consumer Object. More...

def	setObject (self, ior, cons)
	Setting IOR to Consumer. More...

def	subscribeInterfaces (self, connector_profile)
	Subscribe to interface. More...

def	unsubscribeInterfaces (self, connector_profile)
	Unsubscribe interfaces. More...

Public Member Functions inherited from OpenRTM_aist.PortBase.PortBase
def	__del__ (self)
	Destructor. More...

def	__init__ (self, name=None)
	Constructor. More...

def	addProperty (self, key, value)
	Add NameValue data to PortProfile's properties. More...

def	appendInterface (self, instance_name, type_name, pol)
	Append an interface to the PortInterfaceProfile. More...

def	appendProperty (self, key, value)
	Append NameValue data to PortProfile's properties. More...

def	checkPorts (self, ports)
	Existence of ports. More...

def	connect (self, connector_profile)
	[CORBA interface] Connect the Port More...

def	connectNext (self, connector_profile)
	Call notify_connect() of the next Port. More...

def	deleteInterface (self, name, pol)
	Delete an interface from the PortInterfaceProfile. More...

def	disconnect (self, connector_id)
	[CORBA interface] Disconnect the Port More...

def	disconnect_all (self)
	[CORBA interface] Connect the Port More...

def	disconnectNext (self, connector_profile)
	Call notify_disconnect() of the next Port. More...

def	eraseConnectorProfile (self, id_)
	Delete the ConnectorProfile. More...

def	findConnProfile (self, id_)
	Find ConnectorProfile with id. More...

def	findConnProfileIndex (self, id_)
	Find ConnectorProfile with id. More...

def	get_connector_profile (self, connector_id)
	[CORBA interface] Get the ConnectorProfile More...

def	get_connector_profiles (self)
	[CORBA interface] Get the ConnectorProfileList of the Port More...

def	get_port_profile (self)
	[CORBA interface] Get the PortProfile of the Port More...

def	getName (self)
	Get the name of this Port. More...

def	getPortProfile (self)
	Get the PortProfile of the Port. More...

def	getPortRef (self)
	Get the object reference of this Port. More...

def	getProfile (self)
	Get the PortProfile of the Port. More...

def	getUUID (self)
	Get the UUID. More...

def	isEmptyId (self, connector_profile)
	Whether connector_id of ConnectorProfile is empty. More...

def	isExistingConnId (self, id_)
	Whether the given id exists in stored ConnectorProfiles. More...

def	notify_connect (self, connector_profile)
	[CORBA interface] Notify the Ports connection More...

def	notify_disconnect (self, connector_id)
	[CORBA interface] Notify the Ports disconnection More...

def	onConnected (self, portname, profile, ret)

def	onConnectNextport (self, portname, profile, ret)

def	onDisconnected (self, portname, profile, ret)

def	onDisconnectNextport (self, portname, profile, ret)

def	onNotifyConnect (self, portname, profile)

def	onNotifyDisconnect (self, portname, profile)

def	onPublishInterfaces (self, portname, profile, ret)

def	onSubscribeInterfaces (self, portname, profile, ret)

def	onUnsubscribeInterfaces (self, portname, profile)

def	publishInterfaces (self, connector_profile)
	Publish interface information. More...

def	setConnectionLimit (self, limit_value)
	Set the maximum number of connections. More...

def	setName (self, name)
	Set the name of this Port. More...

def	setOnConnected (self, on_connected)
	Setting callback called on connection established. More...

def	setOnConnectionLost (self, on_connection_lost)

def	setOnDisconnected (self, on_disconnected)
	Setting callback called on disconnected. More...

def	setOnPublishInterfaces (self, on_publish)
	Setting callback called on publish interfaces. More...

def	setOnSubscribeInterfaces (self, on_subscribe)
	Setting callback called on publish interfaces. More...

def	setOnUnsubscribeInterfaces (self, on_subscribe)
	Setting callback called on unsubscribe interfaces. More...

def	setOwner (self, owner)
	Set the owner RTObject of the Port. More...

def	setPortConnectListenerHolder (self, portconnListeners)
	Setting PortConnectListener holder. More...

def	setPortRef (self, port_ref)
	Set the object reference of this Port. More...

def	setUUID (self, connector_profile)
	Create and set the UUID to the ConnectorProfile. More...

def	subscribeInterfaces (self, connector_profile)
	Publish interface information. More...

def	unsubscribeInterfaces (self, connector_profile)
	Disconnect interface connection. More...

def	updateConnectorProfile (self, connector_profile)
	Append or update the ConnectorProfile list. More...

def	updateConnectors (self)
	Disconnect ports that doesn't exist. More...

Private Attributes
	_consumers

	_properties

	_providers

Detailed Description

RT Conponent CORBA service/consumer Port.

CorbaPort is an implementation of the Port of RT-Component's that provides user-defined CORBA Object Service and Consumer.

RT-Component can provide user-defined CORBA serivces, which is called RT-Serivce (Provider), through the Ports. RT-Component can also provide place-holder, which is called RT-Serivce Consumer, to use other RT-Component's service.

The CorbaPort can manage any number of Providers and Consumers, can associate Consumers with correspondent Providers when establishing connection among Ports.

Usually, CorbaPort is used like the following.

 RTC::CorbaPort m_port0; // declaration of Port

 MyService_impl m_mysvc0; // Serivce Provider that is provided by the Port
 RTC::CorbaConsumer<YourService> m_cons0; // Consumer of the Port

 // register Service Provider to the Port
 m_port0.registerProvider("MyService0", "Generic", m_mysvc0);
 // register Service Consumer to the Port
 m_port0.registerConsumer("YourService0", "Generic", m_cons0 );

 // after connect established

 m_cons0->your_service_function(); // call a YourService's function

 // in another component that is connected with the Port
 m_cons1->my_service_function(); // call a MyService's function

Registering Service Provider by registerProvider(), it can be used from other RT-Components. Registering Service Consumer by registerConsumer(), other RT-Component's services can be used through the consumer object.

PortInterfaceProfile is a one of the profile information to store Provider interface and Consumer interface information. Tools or other RTCs should call one of the Port::connect() with an appropriate ConnectorProfile.

In addition, the instance name "*" declares a special type of instance.

When the name of the PROVIDED type interface that is the provider interface is "*", Provider interface's instance does not exist at the beginning of connection sequence. The instances will be created dynamically according to the consumer interface requirement at the connection sequence. Although the instance name does not exist at the beginning of connection sequence, the created providers shall publish its references to the ConnectorProfile with interface descriptor adequately in the interface publisher phase of the connection sequence.

If REQUIRED interface name that is Consumer interface name is "*", it shows that one Consumer interface is able to connect with multiple Provider interfaces. (This feature is not implemented.)

The following describes the rules that specify interface connection between ports.

The descriptor format of interfaces associated with Ports is declared as follows. Now some of interface properties are assumed as the followings.

RTC instance name: rtc_iname
Port name: port_name
Interface polarity: if_polarity
Interface type name: if_tname
INterface instance name: if_iname

The interface descriptors shall be declared as follows.

<rtc_iname>.port.<port_name>.<if_polarity>.<if_tname>.<if_iname>

When PROVIDED that is Provider interface properties are the followings,

rtc_iname = MyComp0
port_name = myservice
if_polarity = provided
if_tname = echo_interface
if_iname = echo_interface2 the interface descriptor is here.

MyComp0.port.myservice.provided.echo_interface.echo_interface2

And, when REQUIRED that is Consumer interfaces properties are the followings,

rtc_iname = YourComp0
port_name = yourservice
if_polarity = required
if_tname = hoge_interface
if_iname = hoge_interface1

interface descriptor is as follows.

YourComp0.port.myservice.required.hoge_interface.hoge_inteface1

Specific instance name descriptors that are dynamically generated at the connection time are defined here.

<type_name>*: "Dynamically generated" instance descriptor.
<type_name>+: "Incrementally generated" instance descriptor.

When the "Dynamically generated" instance descriptor: "<type_name>*" is specified as interface descriptor that is required by consumers, the provider will generate a instance. If n consumers who demand a provider by the "<type_name>" descriptor exist, the following relation which processes the call from these consumers by one provider will be established.

 consumer0 ]---<
 consumer1 ]---<  O----[ provider0
 consumer2 ]---<

On the other hand, when incremental generated type instance name descriptor "<type_name>+" is specified as the provider interface descriptor whom consumers demand, provider's instances are dynamically generated for the number of the descriptors "<type_name>+". When n consumers who demand a provider by the descriptor "<type_name>+" exist the following relations in which n providers process each call from the consumers will be established.

 consumer0 ]---<  O----[ provider0
 consumer1 ]---<  O----[ provider1
 consumer2 ]---<  O----[ provider2

Describing the appropriate interface mapping specification in the ConnectorProfile::properties, selective connections between providers/consumers interface can be established at the time of connection. However, when different RTC instances of the same instance name exist in a connection, since an interface descriptor uniqueness cannot be guaranteed, this connection mapping rules cannot be used.

Here, assume that an interface descriptor is given as <if_desc0>, <if_desc1>, .... And assume that the key and the value of NVList in ConnectorProfile::properties are given as "key: value".

Now the case where the service ports of two components are connected is considered. When the service port of each component is the following,

rtc_iname: MyComp0
port_name: mycomp_service
interfaces:
- if_polarity: provided
  if_iname: echo0
  if_tname: Echo
- if_polarity: required
  if_iname: add0
  if_tname: add
rtc_iname: YourComp0
port_name: yourcomp_service
interfaces:
- if_polarity: required
  if_iname: echo9
  if_tname: Echo
- if_polarity: provided
  if_iname: add9
  if_tname: add

      MyComp0                                 YourComp0
     _______ mycomp_service   yourcomp_service ______
            |                                 |
          |~~~|---O echo0         echo9 >---|~~~|
          |   |---< add0          add9  O---|   |
           ~T~                               ~T~
            |                                 |

Assume that connection between echo0 (provider) of MyComp0 component and echo9 (consumer) of YourComp0 component, and add0 (consumer) of MyComp0 and add0 (provider) of YourComp0 is established. In this case, ConnectorProfile is set up as follows.

 ConnectorProfile:
   name: any connector name
   connector_id: empty string
   ports[]: mycomp_service's reference, yourcomp_service's reference
   properties:
     <add0>: <add9>
     <echo9>: <echo0>

Please note that <add0>, <add9>, <echo0> and <echo9> are the following.

 <add0> is MyComp0.port.mycomp_service.required.add.add0
 <add9> is YourComp0.port.yourcomp_service.provided.add.add9
 <echo0> is MyComp0.port.mycomp_service.provided.echo.echo0
 <echo9> is YourComp0.port.yourcomp_service.required.echo.echo9

In the connection process, the provider and the consumer of each port carries out the following process respectively in the virtual functions such as CorbaPort::publishInterfaces() and CorbaPort::subscribeInerfaces().

A provider sets its IOR string as a value and its interface descriptor as a key in the ConnectorProfile::properties in a publishInterfaces() function. Since this interface descriptor's uniqueness is guaranteed in the current connector, the key of NameValue in the ConnectorProfile::properties is unique.

[This functionalities are not implemented] The dynamically generated provider is processed according to the following procedure. The publishInterface() function scans dynamic instance descriptors such as "<type_name>*" and "<type_name>+" in the ConnectorProfile::properties. When the dynamic generation instance descriptor "<tupe_name>*" exists, one instance of provider is generated, and its descriptor and its IOR string are set to ConnectorProfile::properties as the key and the value respectively. Simultaneously, in the ConnectorProfile::properties, all the instance descriptor with the dynamic generation instance name "<type_name>*" will be replaced with newly generated instance descriptor.

When the incremental dynamic generation instance descriptor exists, providers are generated for the number of the descriptors, and its descriptor and its IOR string are set to ConnectorProfile::properties as the key and the value respectively. Simultaneously, in the ConnectorProfile::properties, all the instance descriptor with the dynamic generation instance name "<type_name>+" will be replaced with newly generated instance descriptor.

The providers do not perform particular operation in subscribeInterfaces() function.

The consumers do not perform particular operation in publisherInterfaces() function.

On the other hand, a consumer searches a key-value pair with the key of consumer interface descriptor, and if the pair exists, it obtains provider's descriptor from the value. The consumer searches again a key-value pair with the key of provider interface descriptor, and it obtains provider's reference and the reference is set as the consumer's service object. In addition, reserved string "nil" or "null" are used not to set specific provider.

If consumer's interface descriptors does not exists in the ConnectorProfile::properties, the consumer searches a provider with same type name and instance name, and its reference is set to the consumer. This rule is for only backward compatibility, and it is not recommended from version 1.0.

The correspondence of a provider versus a consumer does not need to be one to one, and the case of one provider to n-consumers and the case of m-providers to one consumer are allowed. The one provider to n-consumers case can be realized by the above mentioned methods. The one consumer to m-provider case can be specified to set the consumer descriptor and comma-separated provider descriptors into the key and the value respectively.

The following option is available to specify the strictness of interfaces connection.

port.connection.strictness: strict, best_effort

strict: The connection is established, if only all the specified consumers are set appropriate references and narrowed successfully.

best_effort: The connection is established without any errors, even if appropriate reference does not exist or reference narrowing fails.

Since: 0.4.0

Definition at line 604 of file CorbaPort.py.

Constructor & Destructor Documentation

def OpenRTM_aist.CorbaPort.CorbaPort.__init__	(	self,
		name
	)

Constructor.

Parameters

name	The name of Port

Definition at line 622 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.__del__	(	self,
		PortBase = `OpenRTM_aist.PortBase`
	)

Definition at line 631 of file CorbaPort.py.

Member Function Documentation

def OpenRTM_aist.CorbaPort.CorbaPort.activateInterfaces ( self )

Activate all Port interfaces.

This operation activate all interfaces that is registered in the ports.

void CorbaPort::activateInterfaces()

Definition at line 810 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.deactivateInterfaces ( self )

Deactivate all Port interfaces.

This operation deactivate all interfaces that is registered in the ports.

void CorbaPort::deactivateInterfaces()

Definition at line 834 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.findProvider	(	self,
		nv,
		cons,
		iorstr
	)

Find out a provider corresponding to the consumer from NVList.

This function finds out a Provider with the key that is matched with Cosumer's name in the CorbaConsumerHolder, extracts IOR and performs narrowing into the Consumer and set it to the Consumer. False is returned when there is no corresponding key and IOR and the narrowing failed.

Parameters

nv	NVlist of ConnectorProfile::properties that includes Provider
cons	a Consumer holder to be matched with a Provider

Returns: bool false is returned if there is no provider for the consumer

virtual bool findProvider(const NVList& nv, CorbaConsumerHolder& cons, std::string& iorstr);

Definition at line 1202 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.findProviderOld	(	self,
		nv,
		cons,
		iorstr
	)

Find out a provider corresponding to the consumer from NVList.

This function is for the old version's compatibility.

This function finds out a Provider with the key that is matched with Cosumer's name in the CorbaConsumerHolder and extracts IOR. False is returned when there is no corresponding key and IOR.

Parameters

nv	NVlist of ConnectorProfile::properties that includes Provider
cons	a Consumer holder to be matched with a Provider
iorstr	variable which is set IOR string

Returns: bool false is returned if there is no provider for the consumer

virtual bool findProviderOld(const NVList&nv, CorbaConsumerHolder& cons, std::string& iorstr);

Definition at line 1273 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.init	(	self,
		prop
	)

Initializing properties.

This operation initializes outport's properties. If a property "connection_limit" is set and appropriate value is set to this property value, the number of maximum connection is set as this value. If the property does not exist or invalid value is set to this property, the maximum number of connection will be set unlimited.

Parameters

prop	properties of the CorbaPort

void init(coil::Properties& prop);

Definition at line 663 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.publishInterfaces	(	self,
		connector_profile
	)

Publish information about interfaces.

This operation publishes Provider interfaces information, which is owned by this port, to the other Ports via ConnectorProfile::properties. Now it is assumed RTC instance name and other information is as follows,

RTC instance name: rtc_iname
Port name: port_name
Interface polarity: if_polarity
Interface type name: if_tname
Interface instance name: if_iname

the following values are stored as the "name" and the "value" of the NameValue typee element in ConnectorProfile::properties.

name <rtc_iname>.port.<port_name>.provided.<if_tname>.<if_iname>
value IOR string value of interface reference

In addition, although the following NameValue values are also stored for the backward compatibility, this will be deleted in the future version.

name port.<if_tname>.<if_iname>
value IOR string value of interface reference

These values are stored in the ConnectorProfile::properties and are propagated to the other Ports. If the Consumer interface exists that requires this Provider interface, it will retrieve reference from the ConnectorProfile and utilize it.

Parameters

connector_profile Connector profile

Returns: The return code of ReturnCode_t type

virtual ReturnCode_t publishInterfaces(ConnectorProfile& connector_profile);

Definition at line 925 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.registerConsumer	(	self,
		instance_name,
		type_name,
		consumer
	)

Register the consumer.

This operation registers a consumer, which is a service placeholder this port requires. These are associated internally with specified instance_name, type_name and Consumer itself to the argument as service's instance name and its type name associated with Consumer. The service Provider interface' references will be set automatically to the Consumer Interface object when connections are established, according to the rules that are described at the subscribeInterfaces() function's documentation.

Parameters

instance_name	Instance name of the service Consumer requires
type_name	Type name of the service Consumer requires
consumer	CORBA service consumer

Returns: False would be returned if the same instance_name was registered

bool registerConsumer(const char* instance_name, const char* type_name, CorbaConsumerBase& consumer);

Definition at line 780 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.registerProvider	(	self,
		instance_name,
		type_name,
		provider
	)

Register the provider.

This operation registers a servant, which is provided in this Port, to the Port. The servant is associated with "instance_name" and "type_name" as the instance name of the servant and as the type name of the servant. A given servant will be stored in the CorbaPort, and this is registered as RTC::PROVIDED interface into the PortInterfaceProfile.

Parameters

instance_name	Instance name of servant
type_name	Type name of the servant
provider	CORBA servant

Returns: Return false if the same name of instance_name is already registered.

bool registerProvider(const char* instance_name, const char* type_name, PortableServer::RefCountServantBase& provider);

Definition at line 717 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.releaseObject	(	self,
		ior,
		cons
	)

Releasing Consumer Object.

This function releases object reference of Consumer. If the given IOR string is different from Consumer's IOR string, it returns false.

Parameters

ior	IOR string
cons	Consumer holder

bool False if IOR and Consumer's IOR are different

bool releaseObject(const std::string& ior, CorbaConsumerHolder& cons);

Definition at line 1370 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.setObject	(	self,
		ior,
		cons
	)

Setting IOR to Consumer.

This function performs narrowing into the Consumer and set it to the Consumer. False is returned when the narrowing failed. But, if IOR string is "null" or "nil", this function returns true.

Parameters

ior	IOR string
cons	Consumer holder

bool false if narrowing failed.

bool setObject(const std::string& ior, CorbaConsumerHolder& cons);

Definition at line 1323 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.subscribeInterfaces	(	self,
		connector_profile
	)

Subscribe to interface.

Retrieve information associated with Provider matches Consumer owned by this port and set the object reference to Consumer.

Now, Consumer is registered as the following:

  PortInterfaceProfile
  {
    instance_name = "PA10_0";
    type_name     = "Manipulator";
    polarity      = REQUIRED;
  }

Find the object reference of Serivce Provider that is registered as the following of other ports:

  PortInterfaceProfile
  {
    instance_name = "PA10_0";
    type_name     = "Manipulator";
    polarity      = PROVIDED;
  }

and set to Consumer. In fact, find NameValue that is registered as the following to ConnectorProfile::properties:

 NameValue = { "port.Manipulator.PA10_0": <Object reference>=""> }

and set the object reference to Consumer.

Parameters

connector_profile Connector profile

Returns: The return code of ReturnCode_t type

virtual ReturnCode_t subscribeInterfaces(const ConnectorProfile& connector_profile);

Definition at line 1089 of file CorbaPort.py.

def OpenRTM_aist.CorbaPort.CorbaPort.unsubscribeInterfaces	(	self,
		connector_profile
	)

Unsubscribe interfaces.

Release all Objects that was set in Consumer associated with the given ConnectorProfile.

Parameters

connector_profile Connector profile

virtual void unsubscribeInterfaces(const ConnectorProfile& connector_profile);

Definition at line 1149 of file CorbaPort.py.

Member Data Documentation

OpenRTM_aist.CorbaPort.CorbaPort._consumers

private

Definition at line 627 of file CorbaPort.py.

OpenRTM_aist.CorbaPort.CorbaPort._properties

private

Definition at line 625 of file CorbaPort.py.

OpenRTM_aist.CorbaPort.CorbaPort._providers

private

Definition at line 626 of file CorbaPort.py.

The documentation for this class was generated from the following file:

CorbaPort.py

Classes

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation