クラス RTC::CorbaPort

RT コンポーネント CORBA provider/consumer 用 Port. [詳細]

#include <CorbaPort.h>

RTC::CorbaPortに対する継承グラフ

構成
class	CorbaConsumerHolder
	Consumer の情報を格納する構造体.
class	CorbaProviderHolder
	Provider の情報を格納する構造体.
struct	unsubscribe
	Consumer のオブジェクトを解放するための Functor.
Public メソッド
	CorbaPort (const char *name)
	コンストラクタ
virtual	~CorbaPort (void)
	仮想デストラクタ
void	init (coil::Properties &prop)
	プロパティの初期化
bool	registerProvider (const char instance_name, const char type_name, PortableServer::RefCountServantBase &provider)
	Provider を登録する.
bool	registerConsumer (const char instance_name, const char type_name, CorbaConsumerBase &consumer)
	Consumer を登録する.
Protected メソッド
virtual ReturnCode_t	publishInterfaces (ConnectorProfile &connector_profile)
	Provider Interface 情報を公開する.
virtual ReturnCode_t	subscribeInterfaces (const ConnectorProfile &connector_profile)
	Provider Interface 情報を取得する.
virtual void	unsubscribeInterfaces (const ConnectorProfile &connector_profile)
	Interface への接続を解除する.
virtual void	activateInterfaces ()
	Port の全てのインターフェースを activates する.
virtual void	deactivateInterfaces ()
	全ての Port のインターフェースを deactivates する
Protected 変数
coil::Properties	m_properties
	プロパティ

説明

RT コンポーネント CORBA provider/consumer 用 Port.

CorbaPort は RT コンポーネントにおいて、ユーザ定義の CORBA オブジェクトサービスおよびコンシューマを提供する Port 実装である。

RT コンポーネントは、Port を介してユーザが定義した CORBA サービスを提供することができ、これを RT Service (Provider) と呼ぶ。また、他の RT コンポーネントのサービスを利用するための CORBA オブジェクトのプレースホルダを提供することができ、これを RT Service Consumer と呼ぶ。 CorbaPort は任意の数の Provider および Consumer を管理することができ、Port 同士を接続する際に対応する Provider と Consumer を適切に関連付けることができる。 CorbaPort は通常以下のように利用される。

 RTC::CorbaPort m_port0; // Port の宣言

 MyService_impl m_mysvc0; // この Port が提供する Serivce Provider
 RTC::CorbaConsumer<YourService> m_cons0; // この Port の Consumer

 // Service Provider を Port に登録
 m_port0.registerProvider("MyService0", "Generic", m_mysvc0);
 // Service Consumer を Port に登録
 m_port0.registerConsumer("YourService0", "Generic", m_cons0 );

 // connect が行われた後

 m_cons0->your_service_function(); // YourService の関数をコール

 // connect された 別のコンポーネントにおいて
 m_cons1->my_service_function(); // MyService の関数をコール

このように、提供したい Service Provider を registerProvider() で登録することにより、他のコンポーネントから利用可能にし、他方、利用したい Service Consumer を registerConsumer() で登録することにより他のコンポーネントの Service をコンポーネント内で利用可能にすることができる。

PortInterfaceProfile は Port に所属するプロバイダもしくはコンシューマインターフェースについての情報を記述するためのプロファイルである。接続を行うツール等は、これらの情報に基づき ConnectorProfile を適切に生成し、接続を構成する Port のうち任意の一つに対して引数に ConnectorProfile を与えて Port::connect() を呼び出す必要がある。

なお、PortInterfaceProfile のインスタンス名 "*" は特殊なインスタンスを表す。

PROVIDEDすなわちプロバイダのインスタンス名が "*" の場合は、接続開始時点ではインスタンスが存在せず、コンシューマの要求に応じて動的にインスタンスを生成するタイプのプロバイダであることを表す。したがって、接続開始時点ではインスタンス名は存在しないが、接続シーケンス中のインターフェースを公開するプロセスにおいて、プロバイダは生成したインスタンスに対応した記述子を ConnectorProfile に適正に設定するものとする。(未実装)

REQUIREDすなわちコンシューマのインスタンス名が "*" の場合は、一つのコンシューマが複数のプロバイダと接続可能なタイプのコンシューマであることを示す。(未実装)

以下は、Port間のインターフェースを接続するために ConnectorProfile にマッピングを記述するためのルールを示す。

Portに付属するインターフェースの指定子のフォーマットを以下のように定める。インターフェースに関するプロパティが以下の場合

RTCインスタンス名: rtc_iname
ポート名: port_name
インターフェース極性: if_polarity
インターフェース型名: if_tname
インターフェースインスタンス名: if_iname

インターフェースの指定子を以下の文字列名称で指定するものとする。

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

PROVIDED(提供)型すなわちプロバイダのインタフェースのプロパティが以下の場合、

rtc_iname = MyComp0
port_name = myservice
if_polarity = provided
if_tname = echo_interface
if_iname = echo_interface2

インターフェース指定子は

MyComp0.port.myservice.provided.echo_interface.echo_interface2

のように記述される。また、同様にREQUIRED(要求)型すなわちコンシューマのインターフェースのプロパティが以下の場合、

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

インターフェース指定子は、

YourComp0.port.myservice.required.hoge_interface.hoge_inteface1

のように記述することができる。

なお、ここで動的生成インターフェースのインスタンスのための特殊なタイプのインスタンス名記述子

<type_name>*: 動的生成型インスタンス名記述子
<type_name>+: インクリメンタル生成型インスタンス名記述子

を定義する。動的生成インターフェースとは、接続時にインスタンスが生成されるタイプのインターフェースである。(未実装)

コンシューマが要求するプロバイダインターフェース記述子に動的生成型インスタンス名記述子 "<type_name>*" が指定された場合、プロバイダはインスタンスを1つ新規に生成する。"<type_name>*" の記述子によりプロバイダを要求する n 個のコンシューマが存在する場合、これらからの要求 (オペレーションコール)を1 つのプロバイダにより処理する関係を構築する(下図)。

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

これに対し、コンシューマが要求するプロバイダインターフェース記述子にインクリメンタル生成型インスタンス名記述子 "<type_name>+" が指定された場合、記述子 "<type_name>+" の数だけプロバイダのインスタンスが動的に生成される。すなわち、"<type_name>+" の記述子によりプロバイダを要求する n 個のコンシューマが存在する場合、n 個のプロバイダがそれぞれの要求を処理する以下のような関係が構築される。

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

接続に際して、ツール等から ConnectorProfile::properties に適切なインターフェースマッピング指定を記述することで、相互のプロバイダ/コンシューマインターフェースを自由に接続することができる。ただし、接続に関わる RTC の中に、異なるインスタンスでありながら、同一のインスタンス名が存在する場合、インターフェース記述子の一意性が保証できないので、この方法による接続性は保証されない。

ここでインターフェース記述子を簡単のために <if_desc0>, <if_desc1>, ... とする。また、ConnectorProfileproperties の NVListの key と value を key: value のように記述するものとする。

いま、2つのコンポーネントのサービスポートを接続する場合を考える。それぞれのコンポーネントのサービスポートが以下の場合、

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~
            |                                 |

MyComp0 の echo0 (プロバイダ) と YourComp0 の echo9 (コンシューマ)、 MyComp0 の add0 (コンシューマ) と YourComp0 の echo9 (プロバイダ) をそれぞれ対にして接続させるものと仮定する。この場合、 ConnectorProfile は以下のように設定する。

 ConnectorProfile:
   name: 任意のコネクタ名
   connector_id: 空文字
   ports[]: mycomp_service の参照, yourcomp_service の参照
   properties:
     <add0>: <add9>
     <echo9>: <echo0>

ただし、それぞれ

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

である。接続プロセスにおいて、各ポートのプロバイダおよびコンシューマは、それぞれ以下の作業を、CorbaPortpublishInterfaces(), CorbaPort::PortsubscribeInterfaces() 仮想関数において行う。

プロバイダは、publishInterfaces() 関数において、自分のインターフェース記述子をキーとし、値にIORの文字列表記したものを ConnectorProfile::properties に設定する。前提として、このインターフェース記述子は今行おうとしているコネクタにおいては一意であるため、同じキーは1つしか存在してはいけない。

[この部分の記述は未実装の機能] なお、動的生成インターフェースについては、以下の手続きに従い処理することとなる。publishInterface() 関数において、動的生成インスタンス名記述子 "<type_name>*" または、インクリメンタル生成型インスタンス名記述子 "<type_name>+" が存在するかどうかを走査する。動的生成インスタンス名記述子 "<type_name>*" が存在する場合、プロバイダのインスタンスを1つ生成し、そのインターフェース指定子を key に、IOR文字列を value に設定するとともに、動的生成インスタンス名記述子 "<type_name>*" を value に含むすべての value 上のインターフェース指定子を、ここで生成したインターフェース指定子に置き換える。

インクリメンタル生成型インスタンス名記述子"<type_name>+" が存在する場合、インスタンス名記述子の数だけプロバイダのインスタンスを生成し、それぞれのインターフェース指定子をkey に、IOR文字列を value に設定するとともに、インクリメンタル生成型インスタンス名記述子 "<type_name>+" を value 含むすべての value 上のインターフェース指定子に対して順に、ここで生成したそれぞれのインターフェース指定子に置き換える。

プロバイダは subscribeInterfaces() では特に操作は行わない。

コンシューマは、 publishInterfaces() においては特に操作を行わない。

一方、 subscribeInterfaces() では、自分の記述子を key とする key-value ペアが存在するかどうか調べ、もし存在すれば、その value に設定されたプロバイダのインターフェース指定子で指定される参照を、さらに ConnectorProfile::properties から探し、それをコンシューマの接続先として設定する。なお、意図的にコンシューマにプロバイダの参照を設定しない場合は、予約文字列 "nil" または "null" を設定するものとする。

コンシューマは、もし自分の記述子が存在しない場合、またはプロバイダの参照が Connector::properties に存在しない場合、コンシューマは、自分のインスタンス名および型名と同一のプロバイダを探し、その参照を自分自身に設定する。これは、OpenRTM-aist-0.4 との互換性を保持するためのルールであり、1.0以降では推奨されない。

プロバイダ対コンシューマの対応は一対一である必要はなく、プロバイダ 1 に対して、コンシューマ n、またはコンシューマ 1 に対してプロバイダ n のケースも許される。プロバイダ 1 に対して、コンシューマ n のケースでは、あるプロバイダの指定子が、複数のコンシューマに対して、上記の方法で指定されることにより、実現される。一方、コンシューマ 1 に対してプロバイダ n のケースでは、コンシューマ指定子の key に対して、複数のプロバイダの指定子がカンマ区切りで列挙される形式となるものとする。

なお、インターフェースの対応関係の厳密さを指定するオプションとして、以下のオプションを指定することができる。

port.connection.strictness: strict, best_effort

strict: すべてのコンシューマに指定した参照が存在し、かつナローイングにも成功しコンシューマに適切にセットできた場合にのみ Port 間の接続を確立する。

best_effort: ナローイング等に失敗した場合でも、エラーを返すことなく Port 間の接続を確立する。

から:: 0.4.0

コンストラクタとデストラクタ

RTC::CorbaPort::CorbaPort ( const char * name )

コンストラクタ

コンストラクタでは、引数に与えられた名前を PortBase に対してセットするとともに、PortProfileproperties に対して

port.port_type: "CorbaPort"

をプロパティとして追加する。

引数:

name

Port の名前

virtual RTC::CorbaPort::~CorbaPort ( void ) [virtual]

仮想デストラクタ

関数

virtual void RTC::CorbaPort::activateInterfaces ( ) [protected, virtual]

Port の全てのインターフェースを activates する.

Port に登録されている全てのインターフェースを activate する。

RTC::PortBaseを実装しています。

virtual void RTC::CorbaPort::deactivateInterfaces ( ) [protected, virtual]

全ての Port のインターフェースを deactivates する

Port に登録されている全てのインターフェースを deactivate する。

RTC::PortBaseを実装しています。

void RTC::CorbaPort::init ( coil::Properties & prop )

プロパティの初期化

OutPortのプロパティを初期化する。このポートへの接続数を指定するプロパティ "connection_limit" が含まれ、適切な数値が設定されている場合、最大接続数としてその数値が設定される。プロパティが設定されていない場合、もしくは適切な値が設定されていない場合には、最大接続数は無制限となる。

引数:

prop

CorbaPort のプロパティ

virtual ReturnCode_t RTC::CorbaPort::publishInterfaces ( ConnectorProfile & connector_profile ) [protected, virtual]

Provider Interface 情報を公開する.

この Port が所有する Provider インターフェースに関する情報を ConnectorProfile::properties に代入し他の Port に対して公開する。今、RTCのインスタンス名等の情報が以下の通りであるとして、

RTCインスタンス名: rtc_iname
ポート名: port_name
インターフェース極性: if_polarity
インターフェース型名: if_tname
インターフェースインスタンス名: if_iname

NameValue 型の ConnectorProfile::properties の name と value として以下のものが格納される。

name <rtc_iname>.port.<port_name>.provided.<if_tname>.<if_iname>
value Provider インターフェースの IOR 文字列

なお、旧バージョンとの互換性のため以下の表記の NameValue も同時に格納されるが、将来のバージョンでは削除される可能性がある。

name port.<if_tname>.<if_iname>
value Provider インターフェースの IOR 文字列

これらの値は ConnectorProfile::properties に格納され、他のポートに対して伝達される。他の Port でこのインターフェースを使用する Consumer が存在すれば、ConnectorProfile からこのキーからオブジェクトリファレンスを取得し何らかの形で使用される。

引数:

connector_profile

コネクタプロファイル

戻り値:: ReturnCode_t 型のリターンコード

RTC::PortBaseを実装しています。

bool RTC::CorbaPort::registerConsumer	(	const char *	instance_name,
		const char *	type_name,
		CorbaConsumerBase &	consumer
	)

Consumer を登録する.

この Port が要求するサービスのプレースホルダであるコンシューマ (Consumer) を登録する。Consumer が関連付けられるサービスのインスタンス名およびタイプ名として、引数に instance_name, type_name および Consumer 自身を与えることにより、内部でこれらが関連付けられる。Port 間の接続 (connect) 時には、subscribeInterfaces() で述べられているルールに基づき、Provider Interface の参照が自動的に Consumer にセットされる。

引数:

	instance_name	Consumer が要求するサービスのインスタンス名
	type_name	Consumer が要求するサービスのタイプ名
	consumer	CORBA サービスコンシューマ

戻り値:: 既に同名の instance_name が登録されていれば false を返す。

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

Provider を登録する.

この Port において提供したいサーバントをこの Port に対して登録する。サーバントは、引数で与えられる instance_name, type_name を、サーバント自身のインスタンス名およびタイプ名として、サーバントに関連付けられる。この関数により、サーバントは CorbaPort 内部に保持されるとともに、PortInterfaceProfile にRTCPROVIDED インターフェースとして登録される。

引数:

	instance_name	サーバントのインスタンス名
	type_name	サーバントのタイプ名
	provider	CORBA サーバント

戻り値:: 既に同名の instance_name が登録されていれば false を返す。

virtual ReturnCode_t RTC::CorbaPort::subscribeInterfaces ( const ConnectorProfile & connector_profile ) [protected, virtual]

Provider Interface 情報を取得する.

この Portが所有する Consumer Interface に適合する Provider Interface に関する情報をConnectorProfileproperties から抽出し Consumer Interface にオブジェクト参照をセットする。

今、RTC のインスタンス名や Consumer Interface 等の情報が以下のとおりであると仮定すると、

RTCインスタンス名: rtc_iname
ポート名: port_name
インターフェース極性: if_polarity
インターフェース型名: if_tname
インターフェースインスタンス名: if_iname

この Consumer Interface を表すインターフェース指定子は以下のように表される。

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

この関数は、まず引数 ConnectorProfile::properties に上記インターフェース指定子をキーとして格納されている Provider Interface 指定子を探し出す。さらに、その Provider Interface 指定子をキーとして格納されている Provider Interface の参照を表す IOR 文字列を取得し、Consumer Interface にセットする。

今、仮に、Provider を prov(n), その参照をIOR(n) さらに Consumer をcons(n) のように記述し、これらすべてのインターフェースの型が同一であり、ConnectorProfile に以下の値が設定されているとする。

 ConnectorProfile::properties =
 {
   prov0: IOR0,
   prov1: IOR1,
   prov2: IOR2,
   cons0: prov2,
   cons1: prov1,
   cons2: prov0
 }

このとき、cons(0..2) にはそれぞれ、参照が以下のようにセットされる。

   cons0 = IOR2
   cons1 = IOR1
   cons2 = IOR0

なお、旧バージョンとの互換性のため、 ConnectorProfile::properties に Consumer Interface をキーとした値がセットされていない場合でも、次のルールが適用される。

今、仮に Consumer Interface が

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

として登録されていれば、他の Port の

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

として登録されている Serivce Provider のオブジェクト参照を探し、 Consumer にセットする。実際には、ConnectorProfileproperties に

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

として登録されている NameValue を探し、そのオブジェクト参照を Consumer にセットする。

引数:

connector_profile

コネクタプロファイル

戻り値:: ReturnCode_t 型のリターンコード

RTC::PortBaseを実装しています。

virtual void RTC::CorbaPort::unsubscribeInterfaces ( const ConnectorProfile & connector_profile ) [protected, virtual]

Interface への接続を解除する.

与えられた ConnectorProfile に関連する Consumer にセットされたすべての Object を解放し接続を解除する。

引数:

connector_profile

コネクタプロファイル

RTC::PortBaseを実装しています。

変数

coil::Properties RTC::CorbaPort::m_properties [protected]

プロパティ

クラス RTC::CorbaPort

構成

Public メソッド

Protected メソッド

Protected 変数

説明

コンストラクタとデストラクタ

関数

変数