[cogl] Don't take internal references on the context

[Robert Bragg <rbragg src gnome org>]

commit 23ce51beba1bb739a224e47614a59327dfbb65af
Author: Robert Bragg <robert linux intel com>
Date:   Mon Sep 10 11:26:17 2012 +0100

    Don't take internal references on the context
    
    We want applications to fully control the lifetime of a CoglContext
    without having to worry that internal resources (such as the default
    2d,3d and rectangle textures, or any caches we maintain) could result in
    circular references that keep the context alive. We also want to avoid
    making CoglContext into a special kind of object that isn't ref-counted
    or that can't be used with object apis such as
    cogl_object_set_user_data. Being able to reliably destroy the context is
    important on platforms such as Android where you may be required
    bring-up and tear-down a CoglContext numerous times throughout the
    applications lifetime. A dissadvantage of this policy is that it is now
    possible to leave other object such as framebuffers in an inconsistent
    state if the context is unreferenced and destroyed. The documentation
    states that all objects that directly or indirectly depend on a context
    that has been destroyed will be left in an inconsistent state and must
    not be accessed thereafter. Applications (such as Android applications)
    that need to cleanly destroy and re-create Cogl resources should make
    sure to manually unref these dependant objects before destroying the
    context.
    
    Reviewed-by: Neil Roberts <neil linux intel com>

 cogl-pango/cogl-pango-fontmap.c        |    3 +--
 cogl-pango/cogl-pango-pipeline-cache.c |    4 +---
 cogl-pango/cogl-pango-render.c         |    6 +-----
 cogl/cogl-bitmap.c                     |    5 +----
 cogl/cogl-buffer.c                     |   16 +++++++---------
 cogl/cogl-context.h                    |   19 +++++++++++++++++++
 cogl/cogl-framebuffer.c                |   31 +++++++++++++++----------------
 cogl/cogl-gles2-context.c              |    4 ----
 cogl/cogl-glib-source.c                |    4 +---
 cogl/cogl-path.c                       |    5 +----
 10 files changed, 47 insertions(+), 50 deletions(-)
---
diff --git a/cogl-pango/cogl-pango-fontmap.c b/cogl-pango/cogl-pango-fontmap.c
index e8df836..5c1a351 100644
--- a/cogl-pango/cogl-pango-fontmap.c
+++ b/cogl-pango/cogl-pango-fontmap.c
@@ -60,7 +60,6 @@ free_priv (gpointer data)
 {
   CoglPangoFontMapPriv *priv = data;
 
-  cogl_object_unref (priv->ctx);
   g_object_unref (priv->renderer);
 
   g_free (priv);
@@ -72,7 +71,7 @@ cogl_pango_font_map_new (CoglContext *context)
   PangoFontMap *fm = pango_cairo_font_map_new ();
   CoglPangoFontMapPriv *priv = g_new0 (CoglPangoFontMapPriv, 1);
 
-  priv->ctx = cogl_object_ref (context);
+  priv->ctx = context;
 
   /* XXX: The public pango api doesn't let us sub-class
    * PangoCairoFontMap so we attach our own private data using qdata
diff --git a/cogl-pango/cogl-pango-pipeline-cache.c b/cogl-pango/cogl-pango-pipeline-cache.c
index 11cbb64..67bb77a 100644
--- a/cogl-pango/cogl-pango-pipeline-cache.c
+++ b/cogl-pango/cogl-pango-pipeline-cache.c
@@ -86,7 +86,7 @@ _cogl_pango_pipeline_cache_new (CoglContext *ctx,
 {
   CoglPangoPipelineCache *cache = g_new (CoglPangoPipelineCache, 1);
 
-  cache->ctx = cogl_object_ref (ctx);
+  cache->ctx = ctx;
 
   /* The key is the pipeline pointer. A reference is taken when the
      pipeline is used as a key so we should unref it again in the
@@ -242,7 +242,5 @@ _cogl_pango_pipeline_cache_free (CoglPangoPipelineCache *cache)
 
   g_hash_table_destroy (cache->hash_table);
 
-  cogl_object_unref (cache->ctx);
-
   g_free (cache);
 }
diff --git a/cogl-pango/cogl-pango-render.c b/cogl-pango/cogl-pango-render.c
index d7c339d..b667a72 100644
--- a/cogl-pango/cogl-pango-render.c
+++ b/cogl-pango/cogl-pango-render.c
@@ -235,7 +235,6 @@ cogl_pango_renderer_set_property (GObject *object,
     {
     case PROP_COGL_CONTEXT:
       renderer->ctx = g_value_get_pointer (value);
-      cogl_object_ref (renderer->ctx);
       break;
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
@@ -275,10 +274,7 @@ cogl_pango_renderer_dispose (GObject *object)
   CoglPangoRenderer *priv = COGL_PANGO_RENDERER (object);
 
   if (priv->ctx)
-    {
-      cogl_object_unref (priv->ctx);
-      priv->ctx = NULL;
-    }
+    priv->ctx = NULL;
 }
 
 static void
diff --git a/cogl/cogl-bitmap.c b/cogl/cogl-bitmap.c
index c6025fd..09c27c6 100644
--- a/cogl/cogl-bitmap.c
+++ b/cogl/cogl-bitmap.c
@@ -51,9 +51,6 @@ _cogl_bitmap_free (CoglBitmap *bmp)
   if (bmp->buffer)
     cogl_object_unref (bmp->buffer);
 
-  if (bmp->context)
-    cogl_object_unref (bmp->context);
-
   g_slice_free (CoglBitmap, bmp);
 }
 
@@ -167,7 +164,7 @@ cogl_bitmap_new_for_data (CoglContext *context,
   g_return_val_if_fail (cogl_is_context (context), NULL);
 
   bmp = g_slice_new (CoglBitmap);
-  bmp->context = cogl_object_ref (context);
+  bmp->context = context;
   bmp->format = format;
   bmp->width = width;
   bmp->height = height;
diff --git a/cogl/cogl-buffer.c b/cogl/cogl-buffer.c
index 92169ee..ffd1ef1 100644
--- a/cogl/cogl-buffer.c
+++ b/cogl/cogl-buffer.c
@@ -300,14 +300,14 @@ _cogl_buffer_initialize (CoglBuffer           *buffer,
                          CoglBufferUsageHint   usage_hint,
                          CoglBufferUpdateHint  update_hint)
 {
-  buffer->context       = cogl_object_ref (context);
-  buffer->flags         = COGL_BUFFER_FLAG_NONE;
+  buffer->context = context;
+  buffer->flags = COGL_BUFFER_FLAG_NONE;
   buffer->store_created = FALSE;
-  buffer->size          = size;
-  buffer->last_target   = default_target;
-  buffer->usage_hint    = usage_hint;
-  buffer->update_hint   = update_hint;
-  buffer->data          = NULL;
+  buffer->size = size;
+  buffer->last_target = default_target;
+  buffer->usage_hint = usage_hint;
+  buffer->update_hint = update_hint;
+  buffer->data = NULL;
   buffer->immutable_ref = 0;
 
   if (use_malloc)
@@ -339,8 +339,6 @@ _cogl_buffer_fini (CoglBuffer *buffer)
     GE( buffer->context, glDeleteBuffers (1, &buffer->gl_handle) );
   else
     g_free (buffer->data);
-
-  cogl_object_unref (buffer->context);
 }
 
 GLenum
diff --git a/cogl/cogl-context.h b/cogl/cogl-context.h
index 78c9f8f..060d497 100644
--- a/cogl/cogl-context.h
+++ b/cogl/cogl-context.h
@@ -66,6 +66,25 @@ G_BEGIN_DECLS
  * design since it helps you write orthogonal rendering components
  * that can all access the same GPU without having to worry about
  * what state other components have left you with.
+ *
+ * <note>Cogl does not maintain internal references to the context for
+ * resources that depend on the context so applications. This is to
+ * help applications control the lifetime a context without us needing to
+ * introduce special api to handle the breakup of internal circular
+ * references due to internal resources and caches associated with the
+ * context.
+ *
+ * One a context has been destroyed then all directly or indirectly
+ * dependant resources will be in an inconsistent state and should not
+ * be manipulated or queried in any way.
+ *
+ * For applications that rely on the operating system to clean up
+ * resources this policy shouldn't affect them, but for applications
+ * that need to carefully destroy and re-create Cogl contexts multiple
+ * times throughout their lifetime (such as Android applications) they
+ * should be careful to destroy all context dependant resources, such as
+ * framebuffers or textures etc before unrefing and destroying the
+ * context.<note>
  */
 
 #define COGL_CONTEXT(OBJECT) ((CoglContext *)OBJECT)
diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c
index 56388da..91d0418 100644
--- a/cogl/cogl-framebuffer.c
+++ b/cogl/cogl-framebuffer.c
@@ -101,24 +101,24 @@ _cogl_framebuffer_init (CoglFramebuffer *framebuffer,
                         int width,
                         int height)
 {
-  framebuffer->context = cogl_object_ref (ctx);
-
-  framebuffer->type             = type;
-  framebuffer->width            = width;
-  framebuffer->height           = height;
-  framebuffer->format           = format;
-  framebuffer->viewport_x       = 0;
-  framebuffer->viewport_y       = 0;
-  framebuffer->viewport_width   = width;
-  framebuffer->viewport_height  = height;
-  framebuffer->dither_enabled   = TRUE;
-
-  framebuffer->modelview_stack  = _cogl_matrix_stack_new ();
+  framebuffer->context = ctx;
+
+  framebuffer->type = type;
+  framebuffer->width = width;
+  framebuffer->height = height;
+  framebuffer->format = format;
+  framebuffer->viewport_x = 0;
+  framebuffer->viewport_y = 0;
+  framebuffer->viewport_width = width;
+  framebuffer->viewport_height = height;
+  framebuffer->dither_enabled = TRUE;
+
+  framebuffer->modelview_stack = _cogl_matrix_stack_new ();
   framebuffer->projection_stack = _cogl_matrix_stack_new ();
 
-  framebuffer->dirty_bitmasks   = TRUE;
+  framebuffer->dirty_bitmasks = TRUE;
 
-  framebuffer->color_mask       = COGL_COLOR_MASK_ALL;
+  framebuffer->color_mask = COGL_COLOR_MASK_ALL;
 
   framebuffer->samples_per_pixel = 0;
 
@@ -179,7 +179,6 @@ _cogl_framebuffer_free (CoglFramebuffer *framebuffer)
   cogl_object_unref (framebuffer->journal);
 
   ctx->framebuffers = g_list_remove (ctx->framebuffers, framebuffer);
-  cogl_object_unref (ctx);
 
   if (ctx->current_draw_buffer == framebuffer)
     ctx->current_draw_buffer = NULL;
diff --git a/cogl/cogl-gles2-context.c b/cogl/cogl-gles2-context.c
index 04ad470..7d29fb2 100644
--- a/cogl/cogl-gles2-context.c
+++ b/cogl/cogl-gles2-context.c
@@ -1530,8 +1530,6 @@ _cogl_gles2_context_free (CoglGLES2Context *gles2_context)
                                  NULL);
     }
 
-  cogl_object_unref (gles2_context->context);
-
   g_free (gles2_context->vtable);
 
   g_free (gles2_context);
@@ -1603,7 +1601,6 @@ cogl_gles2_context_new (CoglContext *ctx, CoglError **error)
 
   gles2_ctx = g_malloc0 (sizeof (CoglGLES2Context));
 
-  cogl_object_ref (ctx);
   gles2_ctx->context = ctx;
 
   COGL_LIST_INIT (&gles2_ctx->foreign_offscreens);
@@ -1612,7 +1609,6 @@ cogl_gles2_context_new (CoglContext *ctx, CoglError **error)
   gles2_ctx->winsys = winsys->context_create_gles2_context (ctx, error);
   if (gles2_ctx->winsys == NULL)
     {
-      cogl_object_unref (gles2_ctx->context);
       g_free (gles2_ctx);
       return NULL;
     }
diff --git a/cogl/cogl-glib-source.c b/cogl/cogl-glib-source.c
index 1c042ee..adbd4d8 100644
--- a/cogl/cogl-glib-source.c
+++ b/cogl/cogl-glib-source.c
@@ -159,8 +159,6 @@ cogl_glib_source_finalize (GSource *source)
 {
   CoglGLibSource *cogl_source = (CoglGLibSource *) source;
 
-  cogl_object_unref (cogl_source->context);
-
   g_array_free (cogl_source->poll_fds, TRUE);
 }
 
@@ -184,7 +182,7 @@ cogl_glib_source_new (CoglContext *context,
                          sizeof (CoglGLibSource));
   cogl_source = (CoglGLibSource *) source;
 
-  cogl_source->context = cogl_object_ref (context);
+  cogl_source->context = context;
   cogl_source->poll_fds = g_array_new (FALSE, FALSE, sizeof (GPollFD));
 
   if (priority != G_PRIORITY_DEFAULT)
diff --git a/cogl/cogl-path.c b/cogl/cogl-path.c
index f14d8c1..15bab83 100644
--- a/cogl/cogl-path.c
+++ b/cogl/cogl-path.c
@@ -96,8 +96,6 @@ _cogl_path_data_unref (CoglPathData *data)
 
       g_array_free (data->path_nodes, TRUE);
 
-      cogl_object_unref (data->context);
-
       g_slice_free (CoglPathData, data);
     }
 }
@@ -124,7 +122,6 @@ _cogl_path_modify (CoglPath *path)
       path->data->fill_attribute_buffer = NULL;
       path->data->stroke_attribute_buffer = NULL;
       path->data->ref_count = 1;
-      cogl_object_ref (path->data->context);
 
       _cogl_path_data_unref (old_data);
     }
@@ -867,7 +864,7 @@ cogl_path_new (CoglContext *context)
   data = path->data = g_slice_new (CoglPathData);
 
   data->ref_count = 1;
-  data->context = cogl_object_ref (context);
+  data->context = context;
   data->fill_rule = COGL_PATH_FILL_RULE_EVEN_ODD;
   data->path_nodes = g_array_new (FALSE, FALSE, sizeof (CoglPathNode));
   data->last_path = 0;