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>

(cherry picked from commit 23ce51beba1bb739a224e47614a59327dfbb65af)

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;

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->context = context;
-  buffer->flags         = COGL_BUFFER_FLAG_NONE;
+  buffer->flags = COGL_BUFFER_FLAG_NONE;
   buffer->store_created = FALSE;
-  buffer->size          = size;
+  buffer->size = size;
-  buffer->last_target   = default_target;
+  buffer->last_target = default_target;
-  buffer->usage_hint    = usage_hint;
+  buffer->usage_hint = usage_hint;
-  buffer->update_hint   = update_hint;
+  buffer->update_hint = update_hint;
-  buffer->data          = NULL;
+  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

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>
  */
 
 #ifdef COGL_ENABLE_EXPERIMENTAL_API

cogl/cogl-framebuffer.c

@@ -162,24 +162,24 @@ _cogl_framebuffer_init (CoglFramebuffer *framebuffer,
                         int width,
                         int height)
 {
-  framebuffer->context = cogl_object_ref (ctx);
+  framebuffer->context = ctx;
 
-  framebuffer->type             = type;
+  framebuffer->type = type;
-  framebuffer->width            = width;
+  framebuffer->width = width;
-  framebuffer->height           = height;
+  framebuffer->height = height;
-  framebuffer->format           = format;
+  framebuffer->format = format;
-  framebuffer->viewport_x       = 0;
+  framebuffer->viewport_x = 0;
-  framebuffer->viewport_y       = 0;
+  framebuffer->viewport_y = 0;
-  framebuffer->viewport_width   = width;
+  framebuffer->viewport_width = width;
-  framebuffer->viewport_height  = height;
+  framebuffer->viewport_height = height;
-  framebuffer->dither_enabled   = TRUE;
+  framebuffer->dither_enabled = TRUE;
 
-  framebuffer->modelview_stack  = _cogl_matrix_stack_new ();
+  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;
 
@@ -240,7 +240,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;

cogl/cogl-gles2-context.c

@@ -1528,8 +1528,6 @@ _cogl_gles2_context_free (CoglGLES2Context *gles2_context)
                                  NULL);
     }
 
-  cogl_object_unref (gles2_context->context);
-
   g_free (gles2_context->vtable);
 
   g_free (gles2_context);
@@ -1601,7 +1599,6 @@ cogl_gles2_context_new (CoglContext *ctx, GError **error)
 
   gles2_ctx = g_malloc0 (sizeof (CoglGLES2Context));
 
-  cogl_object_ref (ctx);
   gles2_ctx->context = ctx;
 
   COGL_LIST_INIT (&gles2_ctx->foreign_offscreens);
@@ -1610,7 +1607,6 @@ cogl_gles2_context_new (CoglContext *ctx, GError **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;
     }

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)

cogl/cogl2-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);
     }
@@ -908,7 +905,7 @@ cogl2_path_new (void)
   data = path->data = g_slice_new (CoglPathData);
 
   data->ref_count = 1;
-  data->context = cogl_object_ref (ctx);
+  data->context = ctx;
   data->fill_rule = COGL_PATH_FILL_RULE_EVEN_ODD;
   data->path_nodes = g_array_new (FALSE, FALSE, sizeof (CoglPathNode));
   data->last_path = 0;