Memory management: Cairo: A Vector Graphics Library

-Memory management

- The objects in cairo can roughly be divided into two types: - reference-counted, opaque types like - cairo_surface_t - and plain structures like - cairo_glyph_t. - cairo_path_t - and - cairo_path_data_t - are special cases and are treated separately in this appendix. -

- Refcounted opaque types all have a - ..._reference() - function to increase the refcount by one and a - ..._destroy() to decrease the refcount - by one. These should not be exposed to the user of the language - binding, but rather used to implement memory management within - the language binding. The simplest way to do memory management - for a language binding is to treat the language binding object - as a simple handle to the cairo object. The language binding - object references the cairo object, and unreferences it when - finalized. This is the recommended method, though there are - a couple of caveats to be noted: -

- Equality won't work as expected. You can have two language - objects for the same cairo and they won't necessarily - compare equal. If the language allows customizing the - equality operation, then this is fixable by comparing - the underlying pointers. It also can be fixed by creating - at most one language object per cairo object, and - uniquifying via a pin table (a hash - table that goes from cairo object to language object). - For cairo_surface_t you can use also - cairo_surface_set_user_data() - instead of a separate pin table. -
-
- Derivation from the language object doesn't work because - you can lose the language object while keeping the Cairo - object. Code like: -
-
```
-public class MySurface (ImageSurface) {
-   public MySurface (width, height) {
-      super (Format.ARGB32, width, height);
-   }
-   public int get42 () {
-      return 42;	  
-   }
-}
-
-   cr = Cairo(MySurface(width, height));
-   surface = cr.getTarget();
-
```
-
- Can result in surface containing an - ImageSurface not a MySurface. - This is not easily fixable without creating memory leaks, - and it's probably best to simply forbid deriving from the - language objects. -
-

- When a plain structure is used as a return value from cairo, - this is done by passing it as a “out parameter”. -

-cairo_font_extents_t extents;      
-
-cairo_font_extents (cr, &extents);

- In a language binding, this should typically be treated - as a return value: -

-FontExtents extents = cr.fontExtents ();

- A language binding has a choice in how it implements the - language objects for plain structures. It can use a pure - language object with fields corresponding to those of the C - structure, and convert from and to the C structure when calling - cairo functions or converting cairo return values. Or it - can keep a pointer to the C structure internally and wrap - it inside a language object much like occurs for refcounted - objects. The choice should be invisible to the user: they should - be able to imagine that it is implemented as a pure language - object. -