Stefan Schirra (stschirr@mpi-sb.mpg.de)
The motivation is to save space by avoiding storing the same data more than once and to save time in the copying procedure. Of course, whether we actually save time and space depends on the size of the data that we would have to copy without sharing representations. The drawback is an indirection in accessing the data. Such an indirection is bad in terms of cache efficiency. Thus there are also non-reference-counting kernels available Simple_cartesian and Simple_homogeneous.
Figure 6.1: Objects using reference counting (bottom) share common representation; copying creates a new handle (drawn at the right) pointing to the same representation as the object copied. Without reference counting (top) all data are copied to the new object (drawn at the right);
The reference counting in the kernel objects is not visible to a user and does not affect the interface of the objects. The representation object is often called the body . The object possibly sharing its representation with others is called a handle , because its data consists of a pointer to its representation object only. If the implementation of the member functions is located with the representation object and the functions in the handle just forward calls to the body, the scheme implements the bridge design pattern, which is used to separate an interface from its implementation. The intent of this design pattern is to allow for exchanging implementations of member functions hidden to the user, especially at runtime.
If CGAL_USE_LEDA is defined and CGAL_NO_LEDA_HANDLE is not defined, the types Handle and Rep are set to the Leda types handle_base and handle_rep , respectively (yes, without a leda_-prefix). Use of the Leda class handle_rep implies that Leda memory management is used for the representation types.
typedef handle_base Handle; typedef handle_rep Rep;
Scavenging Leda, we provide the identical functionality in the Cgal classes Leda_like_handle and Leda_like_rep . If Leda is not available or CGAL_NO_LEDA_HANDLE is set, Handle and Rep correspond to these types.
typedef Leda_like_handle Handle; typedef Leda_like_rep Rep;
Figure 6.2: UML class diagram for Handle & Rep scheme.
class My_rep : public Rep { /*...*/ }; class My_geo_object : public Handle { public: My_geo_object(const My_geo_object& m); My_geo_object(Arg1, Arg2); };
The class My_geo_object is responsible for allocating and constructing the My_rep object ``on the heap''. Typically, a constructor call is forwarded to a corresponding constructor of My_rep. The address of the new My_rep is assigned to PTR inherited from Handle, e.g.:
My_geo_object::My_geo_object(Arg1 a1, Arg2 a2) { PTR = new My_rep(a1, a2); }
The default constructor of Handle is called automatically by the compiler and the reference counting is initialized. You always have to define a copy constructor for My_geo_object and to call the copy constructor of Handle there:
My_geo_object::My_geo_object(const My_geo_object& m) : Handle( m) {}
That's it! There is no need to define a copy assignment operator nor is there a need to define a destructor for the derived class My_geo_object! Handle & Rep does the rest for you! You get this functionality by
#include <CGAL/Handle.h>
It is common practice to add a (protected) member function ptr() to the class My_geo_object, which casts the PTR pointer from Rep* to the actual type My_rep*.
Note that this scheme is meant for non-modifiable types. You are not allowed to modify data in the representation object, because the data are possibly shared with other My_geo_object objects.
Figure 6.3: UML diagram for templated handles.
Kernel objects have used such a handle/rep scheme since release 2.2.
class My_rep : public Ref_counted { /*...*/ }; class My_geo_object : public Handle_for<My_rep> { public: My_geo_object(const My_geo_object& m); My_geo_object(Arg1, Arg2); };
You should also define a copy constructor for My_rep as this may be used in in-place creation in the allocator scheme. The constructors of class My_geo_object are responsible for constructing the My_rep object. Typically, a corresponding constructor call of My_rep is forwarded to Handle_for.
My_geo_object::My_geo_object(Arg1 a1, Arg2 a2) : Handle_for<My_rep>( My_rep(a1, a2)) {}
Sometimes, you have to do some calculation first before you can create a representation object in a constructor of My_rep. Then you can use the initialize_with() member function of Handle_for.
In both cases, Handle_for takes care of allocating space for the new object.
If you define a copy constructor for My_geo_object you have to call the copy constructor of Handle_for there:
My_geo_object::My_geo_object(const My_geo_object& m) : Handle_for<My_rep>( m) {}
That's it! Again, there is no need to define a copy assignment operator nor is there a need to define a destructor for the derived class My_geo_object! Handle_for does the rest for you!
Handle_for provides you with an option to modify the data. There is a copy_on_write() that should be called right before every modification of the data. It ensures that only your data are overwritten:
void My_geo_object::set_x(double d) { copy_on_write(); ptr->x = d; }You get this functionality by
#include <CGAL/Handle_for.h>
class My_geo_object : public Handle_for<My_rep, leda_allocator<My_rep> > { /* ... */ };
The default allocator is defined in
#include <CGAL/memory.h>
See Chapter 7 for more information.