RemoteHandle tutorials

What does what?

There are three classes in play:

• armarx::RemoteHandleControlBlock : Holds the object alive and keeps the reference count. (server side)
• armarx::ClientSideRemoteHandleControlBlock : Increases/Decreases the reference count. (send to the client)
• armarx::RemoteHandle <ProxyType>: Wraps a ClientSideRemoteHandleControlBlock for easy use by the user.

General problems and limitations

Warning

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."
(http://en.cppreference.com/w/cpp/language/operator_member_access#Built-in_member_access_operators)

Leaking

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.

{
    armarx::RemoteHandle<memoryx::CommonStorageInterfacePrx> rh = getCSHandleFromServer();
    //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();
if(rh->ice_isA(memoryx::WorkingMemoryInterface::ice_staticId()))
{
    std::cout << "the mystery is a working memory";
    auto wmrh = armarx::RemoteHandle<memoryx::WorkingMemoryInterfacePrx>::uncheckedCast(rh);
    //use wmrh
}
 
auto csrh = armarx::RemoteHandle<memoryx::CommonStorageInterfacePry>::checkedCast(rh);
if(csrh)
{
    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);
 
    //register
    auto axManager = getArmarXManager();
    ManagementData mdat = RemoteHandleControlBlock::create(
                         getArmarXManager()->getAdapter(),
                         objectProxy,
                         [axManager, objectPtr]
                        {
                            axManager->removeObjectNonBlocking(objectPtr);
                        }
     );
    
    //send to client
    sendToClient(mdat.clientSideRemoteHandleControlBlock);
    //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.
storedDirectHandle->forceDeletion();