Change *_reference() functions to return the object being referenced.

16 files changed, 94 insertions, 49 deletions

diff --git a/ChangeLog b/ChangeLog
index 05d583d5..ef841af7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2005-08-04  Kristian Høgsberg  <krh@redhat.com>
+
+	* src/cairo-font.c: (cairo_font_face_reference),
+	(_cairo_unscaled_font_reference), (cairo_scaled_font_reference):
+	* src/cairo-gstate.c: (_cairo_clip_path_reference):
+	* src/cairo-pattern.c: (cairo_pattern_reference):
+	* src/cairo-pdf-surface.c: (_cairo_pdf_document_reference):
+	* src/cairo-surface.c: (cairo_surface_reference):
+	* src/cairo.c: (cairo_reference):
+	* src/cairo.h:
+	* src/cairoint.h:
+	Change *_reference() functions to return the object being
+	referenced.
+
 2005-07-29  T Rowley  <tim.rowley@gmail.com>
 
 	Reviewed by: otaylor
diff --git a/src/cairo-font-subset.c b/src/cairo-font-subset.c
index 16c52dfd..88008d7e 100644
--- a/src/cairo-font-subset.c
+++ b/src/cairo-font-subset.c
@@ -158,8 +158,7 @@ _cairo_font_subset_create (cairo_unscaled_font_t *unscaled_font)
     if (font == NULL)
 	return NULL;
 
-    font->base.unscaled_font = unscaled_font;
-    _cairo_unscaled_font_reference (unscaled_font);
+    font->base.unscaled_font = _cairo_unscaled_font_reference (unscaled_font);
     font->base.backend = &cairo_pdf_ft_font_backend;
 
     _cairo_array_init (&font->output, sizeof (char));
diff --git a/src/cairo-font.c b/src/cairo-font.c
index dc34ef61..c510bb55 100644
--- a/src/cairo-font.c
+++ b/src/cairo-font.c
@@ -72,17 +72,21 @@ _cairo_font_face_init (cairo_font_face_t               *font_face,
  * Increases the reference count on @font_face by one. This prevents
  * @font_face from being destroyed until a matching call to
  * cairo_font_face_destroy() is made.
+ *
+ * Return value: the referenced #cairo_font_face_t.
  **/
-void
+cairo_font_face_t *
 cairo_font_face_reference (cairo_font_face_t *font_face)
 {
     if (font_face == NULL)
-	return;
+	return NULL;
 
     if (font_face->ref_count == (unsigned int)-1)
-	return;
+	return font_face;
 
     font_face->ref_count++;
+
+    return font_face;
 }
 
 /**
@@ -999,13 +1003,15 @@ _cairo_unscaled_font_init (cairo_unscaled_font_t               *unscaled_font,
     unscaled_font->backend = backend;
 }
 
-void
+cairo_unscaled_font_t *
 _cairo_unscaled_font_reference (cairo_unscaled_font_t *unscaled_font)
 {
     if (unscaled_font == NULL)
-	return;
+	return NULL;
 
     unscaled_font->ref_count++;
+
+    return unscaled_font;
 }
 
 void
@@ -1034,17 +1040,21 @@ _cairo_unscaled_font_destroy (cairo_unscaled_font_t *unscaled_font)
  * Increases the reference count on @scaled_font by one. This prevents
  * @scaled_font from being destroyed until a matching call to
  * cairo_scaled_font_destroy() is made.
+ *
+ * Return value: the referenced #cairo_scaled_font_t.
  **/
-void
+cairo_scaled_font_t *
 cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font)
 {
     if (scaled_font == NULL)
-	return;
+	return NULL;
 
     if (scaled_font->ref_count == (unsigned int)-1)
-	return;
+	return scaled_font;
 
     scaled_font->ref_count++;
+
+    return scaled_font;
 }
 
 /**
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index c934c7de..5587b15a 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -2141,10 +2141,8 @@ _cairo_ft_font_face_create (cairo_ft_unscaled_font_t *unscaled,
 
     /* Looked for an existing matching font face */
     for (font_face = unscaled->faces; font_face; font_face = font_face->next_face) {
-	if (font_face->load_flags == load_flags) {
-	    cairo_font_face_reference (&font_face->base);
-	    return &font_face->base;
-	}
+	if (font_face->load_flags == load_flags)
+	    return cairo_font_face_reference (&font_face->base);
     }
 
     /* No match found, create a new one */
diff --git a/src/cairo-glitz-surface.c b/src/cairo-glitz-surface.c
index 96e92033..402b34f1 100644
--- a/src/cairo-glitz-surface.c
+++ b/src/cairo-glitz-surface.c
@@ -349,8 +349,7 @@ _cairo_glitz_surface_clone_similar (void	    *abstract_surface,
 
     if (src->backend == surface->base.backend)
     {
-	*clone_out = src;
-	cairo_surface_reference (src);
+	*clone_out = cairo_surface_reference (src);	
 	
 	return CAIRO_STATUS_SUCCESS;
     }
diff --git a/src/cairo-gstate.c b/src/cairo-gstate.c
index 121899f0..8db78505 100644
--- a/src/cairo-gstate.c
+++ b/src/cairo-gstate.c
@@ -67,7 +67,7 @@ _cairo_gstate_unset_font (cairo_gstate_t *gstate);
 static void
 _cairo_rectangle_intersect (cairo_rectangle_t *dest, cairo_rectangle_t *src);
 
-static void
+static cairo_clip_path_t *
 _cairo_clip_path_reference (cairo_clip_path_t *clip_path);
 
 static void
@@ -132,8 +132,7 @@ _cairo_gstate_init (cairo_gstate_t  *gstate,
 
     _cairo_pen_init_empty (&gstate->pen_regular);
 
-    gstate->target = target;
-    cairo_surface_reference (gstate->target);
+    gstate->target = cairo_surface_reference (target);
 
     gstate->source = _cairo_pattern_create_solid (CAIRO_COLOR_BLACK);
     if (gstate->source->status)
@@ -1654,13 +1653,15 @@ _cairo_gstate_intersect_clip_path (cairo_gstate_t     *gstate,
     return CAIRO_STATUS_SUCCESS;
 }
 
-static void
+static cairo_clip_path_t *
 _cairo_clip_path_reference (cairo_clip_path_t *clip_path)
 {
     if (clip_path == NULL)
-	return;
+	return NULL;
 
     clip_path->ref_count++;
+
+    return clip_path;
 }
 
 static void
diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index b21cf122..e86ed172 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -408,8 +408,7 @@ _cairo_image_surface_clone_similar (void		*abstract_surface,
     cairo_image_surface_t *surface = abstract_surface;
 
     if (src->backend == surface->base.backend) {
-	*clone_out = src;
-	cairo_surface_reference (src);
+	*clone_out = cairo_surface_reference (src);
 
 	return CAIRO_STATUS_SUCCESS;
     }	
diff --git a/src/cairo-meta-surface.c b/src/cairo-meta-surface.c
index 8a893d66..c2be862e 100644
--- a/src/cairo-meta-surface.c
+++ b/src/cairo-meta-surface.c
@@ -387,8 +387,7 @@ _cairo_meta_surface_show_glyphs (cairo_scaled_font_t	*scaled_font,
 	return CAIRO_STATUS_NO_MEMORY;
 
     command->type = CAIRO_COMMAND_SHOW_GLYPHS;
-    command->scaled_font = scaled_font;
-    cairo_scaled_font_reference (scaled_font);
+    command->scaled_font = cairo_scaled_font_reference (scaled_font);
     command->operator = operator;
     _cairo_pattern_init_copy (&command->pattern.base, pattern);
     command->source_x = source_x;
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index 1fb17217..ca93dde4 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -236,8 +236,7 @@ _cairo_pattern_init_for_surface (cairo_surface_pattern_t *pattern,
 {
     _cairo_pattern_init (&pattern->base, CAIRO_PATTERN_SURFACE);
     
-    pattern->surface = surface;
-    cairo_surface_reference (surface);
+    pattern->surface = cairo_surface_reference (surface);
 }
 
 static void
@@ -489,17 +488,21 @@ cairo_pattern_create_radial (double cx0, double cy0, double radius0,
  * Increases the reference count on @pattern by one. This prevents
  * @pattern from being destroyed until a matching call to
  * cairo_pattern_destroy() is made.
+ *
+ * Return value: the referenced #cairo_pattern_t.
  **/
-void
+cairo_pattern_t *
 cairo_pattern_reference (cairo_pattern_t *pattern)
 {
     if (pattern == NULL)
-	return;
+	return NULL;
 
     if (pattern->ref_count == (unsigned int)-1)
-	return;
+	return pattern;
 
     pattern->ref_count++;
+
+    return pattern;
 }
 
 /**
diff --git a/src/cairo-pdf-surface.c b/src/cairo-pdf-surface.c
index 485c1a0e..c068c8aa 100644
--- a/src/cairo-pdf-surface.c
+++ b/src/cairo-pdf-surface.c
@@ -159,7 +159,7 @@ _cairo_pdf_document_destroy (cairo_pdf_document_t *document);
 static cairo_status_t
 _cairo_pdf_document_finish (cairo_pdf_document_t *document);
 
-static void
+static cairo_pdf_document_t *
 _cairo_pdf_document_reference (cairo_pdf_document_t *document);
 
 static unsigned int
@@ -365,8 +365,7 @@ _cairo_pdf_surface_create_for_document (cairo_pdf_document_t	*document,
     surface->width = width;
     surface->height = height;
 
-    _cairo_pdf_document_reference (document);
-    surface->document = document;
+    surface->document = _cairo_pdf_document_reference (document);
     _cairo_array_init (&surface->streams, sizeof (cairo_pdf_stream_t *));
     _cairo_array_init (&surface->patterns, sizeof (cairo_pdf_resource_t));
     _cairo_array_init (&surface->xobjects, sizeof (cairo_pdf_resource_t));
@@ -1658,10 +1657,12 @@ _cairo_pdf_document_write_xref (cairo_pdf_document_t *document)
     return offset;
 }
 
-static void
+static cairo_pdf_document_t *
 _cairo_pdf_document_reference (cairo_pdf_document_t *document)
 {
     document->ref_count++;
+
+    return document;
 }
 
 static void
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 1920270e..4ff8c700 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -245,18 +245,38 @@ _cairo_surface_get_clip_mode (cairo_surface_t *surface)
 	return CAIRO_CLIP_MODE_MASK;
 }
 
-void
+/**
+ * cairo_surface_reference:
+ * @surface: a #cairo_surface_t
+ * 
+ * Increases the reference count on @surface by one. This prevents
+ * @surface from being destroyed until a matching call to
+ * cairo_surface_destroy() is made.
+ *
+ * Return value: the referenced #cairo_surface_t.
+ **/
+cairo_surface_t *
 cairo_surface_reference (cairo_surface_t *surface)
 {
     if (surface == NULL)
-	return;
+	return NULL;
 
     if (surface->ref_count == (unsigned int)-1)
-	return;
+	return surface;
 
     surface->ref_count++;
+
+    return surface;
 }
 
+/**
+ * cairo_surface_destroy:
+ * @surface: a #cairo_t
+ * 
+ * Decreases the reference count on @surface by one. If the result is
+ * zero, then @surface and all associated resources are freed.  See
+ * cairo_surface_reference().
+ **/
 void
 cairo_surface_destroy (cairo_surface_t *surface)
 {
diff --git a/src/cairo-xcb-surface.c b/src/cairo-xcb-surface.c
index b743cf4d..05e39b55 100644
--- a/src/cairo-xcb-surface.c
+++ b/src/cairo-xcb-surface.c
@@ -643,8 +643,7 @@ _cairo_xcb_surface_clone_similar (void			*abstract_surface,
 	cairo_xcb_surface_t *xcb_src = (cairo_xcb_surface_t *)src;
 
 	if (xcb_src->dpy == surface->dpy) {
-	    *clone_out = src;
-	    cairo_surface_reference (src);
+	    *clone_out = cairo_surface_reference (src);
 	    
 	    return CAIRO_STATUS_SUCCESS;
 	}
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index 22fc6301..4f4e47e3 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -670,8 +670,7 @@ _cairo_xlib_surface_clone_similar (void			*abstract_surface,
 	cairo_xlib_surface_t *xlib_src = (cairo_xlib_surface_t *)src;
 
 	if (_cairo_xlib_surface_same_screen (surface, xlib_src)) {
-	    *clone_out = src;
-	    cairo_surface_reference (src);
+	    *clone_out = cairo_surface_reference (src);
 	    
 	    return CAIRO_STATUS_SUCCESS;
 	}
diff --git a/src/cairo.c b/src/cairo.c
index b4fc5464..060d8fd6 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -178,14 +178,18 @@ cairo_create (cairo_surface_t *target)
  * Increases the reference count on @cr by one. This prevents
  * @cr from being destroyed until a matching call to cairo_destroy() 
  * is made.
+ *
+ * Return value: the referenced #cairo_t.
  **/
-void
+cairo_t *
 cairo_reference (cairo_t *cr)
 {
     if (cr->ref_count == (unsigned int)-1)
-	return;
+	return cr;
     
     cr->ref_count++;
+
+    return cr;
 }
 
 /**
diff --git a/src/cairo.h b/src/cairo.h
index f43d9c58..41310be3 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -222,7 +222,7 @@ typedef cairo_status_t (*cairo_read_func_t) (void		*closure,
 cairo_t *
 cairo_create (cairo_surface_t *target);
 
-void
+cairo_t *
 cairo_reference (cairo_t *cr);
 
 void
@@ -863,7 +863,7 @@ cairo_glyph_path (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);
 
 /* Generic identifier for a font style */
 
-void
+cairo_font_face_t *
 cairo_font_face_reference (cairo_font_face_t *font_face);
 
 void
@@ -890,7 +890,7 @@ cairo_scaled_font_create (cairo_font_face_t          *font_face,
 			  const cairo_matrix_t       *ctm,
 			  const cairo_font_options_t *options);
 
-void
+cairo_scaled_font_t *
 cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
 
 void
@@ -1101,7 +1101,7 @@ cairo_surface_create_similar (cairo_surface_t  *other,
 			      int		width,
 			      int		height);
 
-void
+cairo_surface_t *
 cairo_surface_reference (cairo_surface_t *surface);
 
 void
@@ -1241,7 +1241,7 @@ cairo_pattern_t *
 cairo_pattern_create_radial (double cx0, double cy0, double radius0,
 			     double cx1, double cy1, double radius1);
 
-void
+cairo_pattern_t *
 cairo_pattern_reference (cairo_pattern_t *pattern);
 
 void
diff --git a/src/cairoint.h b/src/cairoint.h
index 794f3409..78387fb0 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -1353,7 +1353,7 @@ cairo_private void
 _cairo_unscaled_font_init (cairo_unscaled_font_t               *font, 
 			   const cairo_unscaled_font_backend_t *backend);
 
-cairo_private void
+cairo_private cairo_unscaled_font_t *
 _cairo_unscaled_font_reference (cairo_unscaled_font_t *font);
 
 cairo_private void