RemoteHandle tutorials

What does what?

There are three classes in play:

General problems and limitations

The QtCreator does not display possible function calls for armarx::RemoteHandle<ProxyType> correctly! You can still call the functions for the ProxyType
It ignores following rule:
"If a user-defined operator-> is provided, the operator-> is called again on the value that it returns, recursively, until an operator-> is reached that returns a plain pointer. After that, built-in semantics are applied to that pointer."


A object may leak if a connection error stops the message send when a handle is deleted (this stops the usecount from reaching zero). The deleter will be called when the armarx::ArmarXManager shuts down. A server can force delete the object by calling armarx::RemoteHandleControlBlock::forceDeletion on the direct handle returned by RemoteHandleControlBlock::create

Premature deletion

A object may be deleted with handles still alive if:

  1. the object's deletion was forced by calling armarx::RemoteHandleControlBlock::forceDeletion
  2. a scenario equivalent to this:
    1. pc A has the object and sends a handle to B
    2. pc B has now the only handle
    3. pc B now sends the handle to pc C and delets the handle before C deserialized the object (this could be done via a broadcast)
    4. The handle is deserialized after the deletion timeout set via property (default 3 sec) has passed.

This scenario 2) is possible but should not happen on a stable LAN if ice objects are not keept in a serialized form for a longer period

The client side

You will probably know the type of proxy to expect. E.g.: A memoryx::CommonStorageInterfacePrx.

//now use rh just as you would use a proxy
//rh is out of scope now.
//the server decrements the reference count.

If you don't know the proxy type to expect:

armarx::RemoteHandle<Ice::ObjectPrx> rh = getMysteryHandleFromServer();
std::cout << "the mystery is a working memory";
//use wmrh
std::cout << "the mystery is a common storage";
//use csrh

The server side

Create a armarx::RemoteHandleControlBlock like this:

//get the stuff we want to register
auto objectPtr = createObject();
getArmarXManager()->addObject(objectPtr, true, "somename");
//the self proxy could still be null => wait for it
auto objectProxy = objectPtr->getProxy(-1);
auto axManager = getArmarXManager();
ManagementData mdat = RemoteHandleControlBlock::create(
[axManager, objectPtr]
//send to client
//maybe store mdat.directHandle
//mdat.directHandle is now out of scope
//it is ok if it was deleted

Maybe you want to clean up (if you don't do this and your network is unstable you may leak the armarx::RemoteHandle until the armarx::ArmarXManager shuts down):

//you are shutting down your server and want to make sure the created \ref armarx::RemoteHandle is deleted now.
RemoteHandle< TargetPrxType > uncheckedCast() const
Definition: RemoteHandle.h:161
The RemoteHandle class wrapps a ClientSideRemoteHandleControlBlock and can be used just as a Ice prox...
Definition: RemoteHandle.h:45
RemoteHandle< TargetPrxType > checkedCast() const
Definition: RemoteHandle.h:171