There are three methods of Object which can be used to request delivery (migration) of the object to another object: migrate_to(), schedule_to() and deliver_asap_to().

void Object::migrate_to
    (
    WeakPointer< Object > destination_object,
    const STime &         delivery_time,
    bool                  notify = true
    );

EventHandle Object::schedule_to
    (
    WeakPointer< Object > destination_object,
    const STime &         delivery_time,
    bool                  notify = true
    );
    
void Object::deliver_asap_to
    (
    WeakPointer< Object > destination_object,
    bool                  can_deliver_to_replica = false
    );

The destination_object specifies the object to which the migrated object should be delivered.

The delivery_time is the time when the migrated object should be delivered to the destination object. Note that that the Core doesn't ensure that the object will be delivered exactly at the specified time to the destination object. The delivery_time specifies only when the migration will begin because there is no way how to detect how much time the migration will take since the destination object must be first found in the simulation and also the network transmission time is unpredictable. The migrated object will be delivered exactly at the specified time only if the destination object is on the same node as the migrated object (in such case the migrated object is not migrated at all). The variable duration of the migration should not be a problem because once the migrated object is delivered, the Core tells him the original delivery_time and so the object can easily compute how much time the migration took and do whatever is appropriate.

The notify specifies whether the migrated object should be notified when it is delivered to the destination object. If it is true, the Core calls delivered_to() (or delivery_failed() in case the delivery failed) on the migrated object once it is delivered to the destination object. If the notify is false, the migrated object is not notified of the finished migration (neither delivered_to() nor delivery_failed() is called).

In most cases you will request deliveries with notifications (the notify set to true, which is the default) since the delivered objects will often do something with the destination objects (call their methods, access their properties etc).

Migrations without notifications are useful when you want to migrate an object without letting it to know. In such case the migration to the destination object just means moving the object to the node where the destination object resides. This principle is used by the Core to distribute managed objects among server nodes when performing load balancing (Appendix B, Load Balancing).

The migrate_to() tells the object to migrate at specified time to the destination_object.

The deliver_asap_to() tells the object to migrate to the destination_object as soon as possible. The major difference from general migrate_to is that the object is delivered immediatelly if destination_object is a local object instead of scheduling the migration so that it could be processed at next simulation tick (if possible). If destination_object is a local object, migration callbacks (see Section 6.6, “Migration Callbacks”) will already have been executed by the time when deliver_asap_to() returns. If the object is not local a migration to the destination_object is scheduled to current simulation time and the method behaves like migrate_to().

The can_deliver_to_replica determines whether the object can be delivered to a consistent local replica of the destination_object. If a migration is scheduled the object is always delivered to the original object.

schedule_to() does the same what migrate_to() does with the only difference: the methods returns a “handle to the scheduled migration” (the handle is called EventHandle because scheduled migrations are implemented as events of the objects but it is nothing you should worry about). The returned handle can be used to cancel the migration. Note that the migration can be cancelled only if you have both the handle to the migration and strong pointer to the migrated object (i.e. the object is local). In other cases the result of the cancellation is undefined. The migration may but also may not be cancelled.

Corresponding property for the EventHandle is PEventHandle. To cancel the migration call kill() method on the handle:

void EventHandle::kill();
void PEventHandle::kill();

Note that there is also performace difference between migrate_to() and schedule_to(). The latter adds extra data to the object which must be transferred over the network when the object is migrated. If you don't need to cancel migrations you should always use the migrate_to() method.