Open topic with navigation

Tutorial B: Abandoned Object Adoption

This tutorial demonstrates the adoption of an abandoned object.

About Abandoned Object Adoption

In the event that a saved, named object is "abandoned" (for example, its owner agent is terminated or explicitly abandons the object), another agent can take ownership of the object. Any agent can adopt an abandoned object by trying to create an object with the same name, type, and model location. If the object doesn't exist, then it will be created; if it does exist and is abandoned, then it will be adopted. Agents can also have callbacks triggered when an object that they are subscribed to is abandoned or adopted.

Note: To read more about object adoption, see "Adoption of Abandoned Objects".

Tutorial Overview

In this tutorial, you use Distrix System Builder to create a simple project based on the "Pass-the-Package" party game. In Pass-the-Package, a gift is wrapped in several layers of gift-wrap and as it is passed around a circle, each person removes a layer of wrap. The person who unwraps the last layer wins the gift.

Your project will have one object, which is the "gift", and two agents, which are the gift-giver and the unwrapper.

At run time, the gift-giver agent sets the number of gift wrap layers, then abandons the object. Instances of the unwrapper agent wait for a callback to indicate that the object has been abandoned and each attempts to adopt the object.

If an unwrapper agent fails to adopt the object, it waits until the object is abandoned again. If an unwrapper agent successfully adopts the object, it decrements the number of gift wrap layers, then ends its own process, which abandons the object. This procedure is repeated until there are no gift wrap layers left. The unwrapper agent that reduces the gift wrap layers to zero is the game's winner.