Managed pointers are implemented as template classes that represent the reference and are accompanied by a set of overloaded operators so that the classes could mimic the C++ pointers. Their declaration looks like this:

/* Pointers with local dereference semantics. */

template< class Type, class Cast = DefaultCast< Type > >
class Pointer;

template< class Type, class Cast = DefaultCast< Type > >
class WeakPointer;

template< class Type, class Cast = DefaultCast< Type > >
class PPointer;

template< class Type, class Cast = DefaultCast< Type > >
class PWeakPointer;

/* Pointers with remote dereference semantics (RPC). */

template< class Type >
class Remote;

template< class Type >
class PRemote;

For example Pointer< MyObject > represents strong stack pointer to MyObject. Declarations of other pointer types would look the same.

	Note
	Pointers are default-initialized to point to NULL_ID.

Note

We have not explained the meaning of the optional Cast parameter yet. It refers to the cast object functor that is responsible for returning of the correct C++ pointer if managed pointer is locally dereferenced. Its purpose is to convert a C++ pointer to general object to a pointer to Type. If managed class inherits Type more times, Type is ambiguous within the class hierarchy and pointer dereference will fail. In that case user has to provide own cast object that would resolve such ambiguity. This is described in the following section. However if you do not use multiple inheritance, do not inherit the same class multiple times (for example virtual inheritance is used, which is supported by Massiv) or do not want to create pointers to ambiguous Types, you can skip this section.

One of the problems the Core has to deal with is what component of the referenced object should be accessed if pointer is dereferenced. Note that the reference must be represented at least by ObjectId of the referenced object and Type of the referenced component. Obviously for some object instances this would not be sufficient if Type is inherited multiple times by those instances. Because of this, the reference representation was augmented to hold a Cast cast object. Cast object represents the referenced component more precisely - it identifies not only its Type but also provides code how the component should be accessed (cast from C++ pointer to general object to the C++ pointer to the requested component).

The Core provides default implementation of the cast object called Massiv::Core::DefaultCast. It works correctly as long as Type is inherited once only by the relevant class. If that is not true then the default cast object would not be able to resolve the Type ambiguity and the dereference may fail. Then user has to implement its own cast object.

Any cast object must inherit from Massiv::Core::CastObject.

class CastObject
    {
public:
    virtual VariantPointer operator()( ObjectProperty * object ) const = 0;
    /* Implements cast from ObjectProperty * to requested component. */
    virtual const std::type_info & get_target_type_info() const = 0;
    /* Returns type information of the referenced component. */
    };

For more information on how cast object should be implemented consult Massiv::Core::CastObject in the Massiv Core Programmer's Documentation.

	Note
	User-defined cast objects are utilized by pointers with local dereference semantics only. Pointers with remote dereference semantics operate as if default cast object was used (requested interface must be unique for the referenced object or the operations would fail).

Ability to change pointer values and reference other objects is one of the key operations pointers have to support. Managed pointers overload operator=() and allow for such changes. Any such operation results in change of the pointer state, namely ObjectId of the referenced object. The actual assignment operation is preceded by optional implicit pointer conversions and validation or verification of the assignment.

Implicit pointer conversions:

Assignment verification:

In the following table there are described supported assignment operations. The table shows what operands can be used as arguments to pointer's operator=() and what checks (compile-time or run-time) are performed. Run-time errors are signalled to the application by raising exceptions (see Section 5.3.11, “Exceptions”) or asserts (program logic errors, static errors).

	Note
	Managed pointers implement the same set of constructors with similar semantics.

The use of the presented variants should be quite straightforward and is illustrated at the end of the section. Nevertheless there are some issues that need to be addressed before and will be explained now:

An example:

class X : public Object { ... };
class Y : public X { ... };
class Z : public Y { Pointer< Z > method(); };
...
Pointer< Z > Z::method()
  {
  Pointer< X > ptr_x;
  Pointer< Y > ptr_y;
  Pointer< X > other_ptr_x;
  WeakPointer< X > weak_ptr_x;

  ptr_y = CreateObject< Y >(); 
  ptr_x = ptr_y; 
  other_ptr_x = ptr_x;
  weak_ptr_x = ptr_x; 
  //ptr_y = ptr_x; /* Compile-time error. Need explicit cast. */
  ptr_y = ptr_x.convert(); 
  ptr_x = null;

  return this;
  }

	This is how stand-alone objects are created. You should already be familiar with this construct.
	Implicit pointer conversion (upcast).
	Implicit pointer conversion (mutation).
	Explicit pointer conversion (downcast). Use method convert() to force an explicit cast of the pointer.

Another important feature managed pointers support is the ability to compare them. Both comparing with managed pointers and C++ pointers have been implemented, however with different semantics. When comparing two managed pointers, ObjectIds of the referenced objects are compared only, the other characteristics, mainly what components are referenced, are ignored. When comparing a managed pointer with a C++ pointer, pointer to the referenced component (as returned by the cast object) is compared with the C++ pointer.

	Note
	The actual implementation does not follow the wording exactly, which allows for various optimizations. However the effect is the same.

Managed pointers overload operator==() and operator!=() so that they could be compared as C++ pointers. Since the results of comparisons do not depend on the order of their operands it is sufficient to summary all the valid operand combinations in the following table. The operations will always succeed.

	Warning
	Comparing pointers with ObjectId is illegal as well as casting pointers explicitly for the purposes of comparison (one of the operands is a product of convert() method). Managed pointers with different characteristics can be compared without a cast.

Warning

Managed pointers are compared by ObjectIds only. This can yield surprising results in multiple inheritance hierarchies. For example if a class Foo was inherited multiple times to object A, the result of the comparison of Pointer< Foo > and C++ this pointing to the same object A would always be "not equal" as Foo would be ambiguous. However if this was converted to a managed pointer before and then compared with Pointer< Foo > the result would be "equal" as both the pointers would reference the same object. In single inheritance hierarchies the results will be exactly the same as if C++ pointers were compared (the pointers either point to the unrelated class hierarchies, and then object ids are different, or to the same hierarchy and simple object id test is sufficient because of pointer subsumption).

Managed pointers provide a secure way to dereference self and access components of referenced objects. When dereferenced, an active proxy ^[1] object, bound to the referenced object, is returned by value. Its type and implementation depends on pointer deference semantics. The proxy then delegates the access to either bound local object (and fails if there is none; proxy with local dereference semantics) or a local RPC stub that translates the access to a RPC call on the bound remote object (proxy with remote dereference semantics).

If a pointer has a local dereference semantics, the proxy tests if referenced component can be accessed locally (referenced object or its replica must be present on the local system and the component must not be ambiguous), pins the object to the local node (object is active since then) and gains full access to the object's component (as determined by pointer's cast object). When the component is no longer dereferenced the object is ready to be unpinned. Until unpinned, the object remains active and can not be deleted or can not migrate. If bound object is not present on the local node, nor its replica, the dereference will fail.

Proxy with remote semantics access methods described by IDL only. Stubs, generated for each RPC method, are responsible for translation of the local call to a RPC call. For information how RPC works see Chapter 8, Remote Procedure Call.

Pointers overload operator->() so that they could be dereferenced in usual C++ way. Attempts to dereference invalid pointers (point to NULL_ID, ambiguous or unsupported components, remote objects, etc.) are rejected and one of the following exceptions will be thrown:

	Note
	The errors that could not be catched at assign time will probably be detected at dereference time. Remember that no interface test is performed if the type information of the referenced object is unavailable. However the object could migrate to the local node in the mean time and the interface test would be then performed at the time of the pointer dereference.

Unlike C++ pointers, managed pointers define additional member methods that can be used to query pointer state. This information can be used to test if actual pointer operation (for example an assignment to another pointer type, a pointer dereference, etc.) will succeed. Since some of the pointer functionality is turned off in release mode (see Section 5.3.13, “Differences In Debug And Release Mode”), incorrect use will either be not detected, program will simply crash or its state become inconsistent.

	Warning
	Programmer must be aware of the differences and must test in advance if certain operations could be processed safely.

The following table lists some of the most useful methods. For the complete list consult the Massiv Core Programmer's Documentation.

An example:

class MyClass : public Object { ... };
class MyDerivedClass : public MyClass { public: PInt32 my_integer; ... };
...
WeakPointer< MyClass > ptr = ...;
try
  {
  Pointer< MyDerivedClass > ptr_derived = ptr.convert(); 
  ptr_derived->my_integer = 2;
  }
catch( Throwable & )
  {
  }
        

Pointer conversion may fail because of two reasons. Either ptr refers to a remote object (thus conversion to a strong pointer is rejected) or the referenced object does not inherit from MyDerivedClass.

The same program can be rewritten so that no exceptions would be raised:

WeakPointer< MyClass > ptr = ...;
if( ptr.is_local() && ptr.inherits( typeid( MyDerivedClass ) )
  {
  Pointer< MyDerivedClass > ptr_derived = ptr.convert();
  ptr_derived->my_integer = 2;
  }

Pointer properties can be anotated by pointer replication flags that are used for implicit definitions of migration and replication groups of objects. The flags are set by IDL ptr_repflags property attribute.

Replication group of an object is defined as a maximal set of objects reachable from that object over bidirectional pointer properties whose pointer replication flags match a given mask. Replication flags masks are "yes-no" pairs that specify what bits of pointer replication flags must be set (yes bits) and what bits must not be set (no bits). Replication groups induced by a predefined fixed [ REPMASK_MIGRATE_YES, REPMASK_MIGRATE_NO ] pointer replication flags mask are called migration groups of objects. The mask is chosen so that any replication group (induced by a different mask) is a subset of the corresponding migration group. During the enumeration process pointer properties are treated as if they were bidirectional.

Replication groups are always defined with respect to a specified mask. There is no single replication group of an object. For example the replication group of an object for the purposes of its replication from a server to a server node (induced by one mask) may be different from the replication group of the same object for the purposes of its replication from a server to a client node (induced by another mask). The masks are set globally for all allowed replication destination node types. When an object should be replicated, the Core determines type of the replication (for example “replication to server”), looks up the replication mask related to the particular replication type and enumerates the replication group of the object using the obtained mask. Specified bit of the pointer replication flags triggers replication of the referenced and the owner object to the corresponding node type.

	Note
	For example when replicating a Player object to a server node, not only Player but also its inventory and other helper objects (part of Player's migration group) would be replicated. However when replicating the same Player object to a client node, only the Player object and its inventory would be replicated. This is controlled by the setting of the pointer replication flags.

Migration groups are replication groups with a predefined REPFLAGS_MIGRATE pointer replication flags bit set. If this bit is on then the referenced object will always be (must be) present on the same node as the object that owns the pointer and the pointer will implicitly define a migration group of objects. It is also said that the pointer triggers the migration of the referenced object or the owner object if the other object migrates. Such a pointer need not be strong. However the Core automatically sets this bit for strong pointer properties.

Note

Pointer properties that define replication/migration groups are treated bidirectionally. This is needed to ensure that strong pointers always reference local objects, for example. Otherwise if B migrated to an another node, the strong pointer from A to B would be pointing to a remote object. Although this makes implementation of ObjectPointer and group enumeration more complex this proved to be very useful. For example Player object can reference its Inventory object by a single strong pointer and both migration groups of Player and Inventory are the same (Inventory need not reference Player). Together with implicit replication/migration group definitions this is one of the key properties that make the Massiv unique.

Confused? See the example:

class Inventory : public Object { ... }; /* All ptr_repflags = 0 */
class Account : public Object { ... };   /* All ptr_repflags = 0 */

class MapSector : public Object
  {
public:
  ...
  /* ptr_repflags = 0 */
  PRemote< MapSector > neighbor[ 8 ];
  };

class Player : public Object
  {
public:
  ...
  /* ptr_repflags = MIGRATE | SERVER_BIT | STANDARD_CLIENT_BIT */
  PPointer< Inventory > inventory;

  /* ptr_repflags = MIGRATE | SERVER_BIT */
  PPointer< Account >   account;

  /* ptr_repflags = MIGRATE */
  PPointer< MapSector > sector;
  };
...
Pointer< Player > player = ...;
Pointer< Inventory > inventory = ...;
Pointer< Account > account = ...;
Pointer< MapSector > sector = ...;

player->inventory = inventory;
player->account = account;
player->sector = sector;

Suppose that we have named pointer replication flags bits so that MIGRATE triggers object migration (defines a migration group), SERVER_BIT triggers replication to server nodes and STANDARD_CLIENT_BIT replication to standard client nodes. Inventory, Account and MapSector objects contain weak pointers with ptr_repflags = 0 only, then:

Note

In the example we were assigning strong pointers to the Player object which caused the merging of the migration groups resulting in the creation of a single migration group containing all the involved objects. First, the migration group of the Inventory object and the Player object was merged, then the migration group of the Account object was joined, etc. Since we were working with strong pointers all the groups had been local. If a remote migration group should have been merged, our Player object would have to migrate to the remote group (taking its current migration group with self) so that the join could have been finished on the remote node. See Section 6.5, “Requesting Migration”.

	Note
	Right now you might be confused. How do I assign ptr_repflags to a pointer? What values can be assignmed to ptr_repflags? The answer is: ptr_repflags is an attribute of pointer properties, it's value is specified in IDL. For more information see Section 7.5, “Replication-related IDL Attributes” and Section 10.8, “Attributes”.

When creating recursive data structures, one has to use pointers to forward declared classes in order to avoid cyclic header inclusion. Pointer implementation allows to declare managed pointers to forward declared classes. However at the time of the pointer use (for example dereference), the referenced class must have already been seen by the compiler. This requires to organize source code in such a way that headers contain class declarations only and the full definition, including method bodies, is provided in .cpp files.

Header file:

...
class A;
class B;

class A : public Object
  {
public:
  void set( Pointer< B > ptr );
  PPointer< B > ptr_b;
  ...
  };

class B : public Object
  {
public:
  void set( Pointer< A > ptr );
  PPointer< A > ptr_a;
  ...
  };

CPP file:

...
void A::set( Pointer< B > ptr )
  {
  ptr_b = ptr;
  }

void B::set( Pointer< A > ptr )
  {
  ptr_a = ptr;
  }

	Note
	Classes must be forward-declared in the IDL too. See Section 10.9.1, “Forward Declaration”.

Pointer property semantics changes if the property is actually a replica. In that case the object that owns the property is also a replica. This means that pointer's static characteristics will be partially ignored. In particular all pointer property replicas are considered weak regardless to their static characteristics. That is because not replicated portions of migration groups, thus remote, can be referenced from the replicated parts by originally strong pointers.

	Note
	In the example above the Player object replicated to a standard client node would have its pointers to Account and MapSector pointing to the original (remote) objects and the objects would not be replicated to that node.

	Warning
	This has a consequence that the conversion of PPointer< Object > to Pointer< Object > can fail if the property is a pointer replica since we are effectively converting a weak pointer property to a strong stack pointer.

The other issue is how object replicas can be accessed by other non-replica pointers (either regular stack pointers or non-replica pointer properties). Let us note that object replicas have the same object id as the original objects and are accessible by pointers with local dereference semantics only. There are never the original object and its replica present on the same node at the same time (for more information see Section 7.4, “Accessing Object Replicas”). Obviously strong pointer properties can not reference object replicas because the corresponding original objects are remote. Also strong stack pointers can not reference object replicas (such references would prevent the Core from updating strong-referenced replicas and could block incoming migrations too, see Section 7.10, “Allowed and Illegal Operations”). However they can be referenced by weak pointers of any other characteristics.

	Warning
	Calling a SRPC from within a replica (if an object replica is active) is forbidden as it would prevent the Core from updating the replica.

Pointer policies state what pointers, with given characteristics, can reference particular objects and what the Core guarantees if such a pointer exists. The following object and pointer properties are investigated:

Although most of the policies have already been mentioned in the previous sections they have been summarized in the following lists and tables.

Policies applicable to both stack pointers and pointer properties:

The following policies are applicable to pointer properties only. They ensure migration groups consistency. The policies are violated due to program logic errors only and they are signalled to the application through a generic PointerPolicyViolationException exception:

Most of the policies take effect if doing implicit pointer conversions when pointer characteristics changes (pointer mutation). The behavior is summarized in the following table. It can be seen that conversions to weak pointers always succeed (the plus signs) and the other conversions fail if the referenced object is remote or an object replica :

	Note
	The following table ommits several kinds of pointers. It is because a mutation to them will always succeed. They are: WeakPointer< X >, Remote< X >, PWeakPointer< X > and PRemote< X >.

There is always a way to check if certain operation is correct so that the policy violation exception could be avoided. The check can be done on the application level by using these methods:

Pointer subsystem throws managed exceptions if an incorrect use of a pointer is detected. If an exception is thrown, the state of the involved pointer is rollbacked to a previous consistent state. The following table describes the exceptions from the point of view of the pointer subsystem, the exceptions can be used by other subsystems as well:

This chapter summarizes the basic differences between C++ pointers and managed pointers. As could have been seen, managed pointers try to imitate C++ pointers as authentically as possible, but also add non-trivial extensions such as type and reference safety or implicit migration and replication group definition. Some of the features already supported by C++ pointers are implemented by managed pointers differently (or not at all) and that's why this chapter is present:

Full pointer policy testing can be quite an expensive task. However most of the policies that are checked at run-time are intended to catch program logic errors. This means that the policy violation is often systematic and once the program has been debugged and it has been verified that the policies are no longer violated, the checks can be turned off and gain significant program speed up.

If the application is compiled in debug mode all the tests that can be performed locally are turned on. This includes full pointer policy testing. When compiled in release mode the following tests are turned off or are different:

	Warning
	Application programmer must be aware of the differences. The program is considered ill formed if it violates the policies that are checked in debug mode only. Programmer can check the policy on the application level if needed.

Managed pointers can be combined with C++ references pointing to object members if extra attention is given. These techniques are considered advanced as one could get along with managed pointers only. For example in Java you can not create a reference to an object member.

Warning

In Massiv it is okay to create and pass short-time aliasing C++ references pointing to local members to other local methods as far as the object that owns the referenced members is (and will remain) active. Such references must not be stored (kept) by the callee. Similarly, C++ references to data allocated on the stack can be passed to local methods if they are released when the callee exits. Simple standard scoping rules will help you to understand this.

void print( const Property & p )
  {
  std::cout << p;
  }

void MyObject::method()
  { 
  std::cout << *this;
  print( this->my_property ); 
  }

/*
const Property & MyObject::get_my_property() const
  {
  return this->my_property; 
  }
*/

	Suppose that MyObject instance has been called through a managed pointer. MyObject instance has already been pinned when program got to this point. Application can now manipulate with MyObject instance as usually.
	Pass my_property to print() by C++ reference, print() must forget the reference at its exit.
	Wrong! Can not export a C++ reference to an object that won't be active any more.