GNOME.org
 

[clutter] Move towards an alloc/init pair for base types

commit bc914bb8a243e102dc3412edcf3b5bb5e9dccf0d
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Wed Apr 18 17:31:28 2012 +0100

    Move towards an alloc/init pair for base types
    
    Instead of a single new() constructor that both allocates and
    initializes, split the allocation and initialization into two separate
    functions for types that are typically used on the stack, and rarely
    allocated on the heap, like ClutterPoint and friends.
    
    This is also applied retroactively to ClutterActorBox and ClutterVertex,
    given that the same considerations on usage apply to them as well; we
    can add a return value to clutter_actor_box_init() and
    clutter_vertex_init() in an ABI-compatible way, so that
    clutter_actor_box_new() and clutter_vertex_new() can be effectively
    reimplemented as "init (alloc ())".

 clutter/clutter-actor-box.c  |   45 +++++++++---
 clutter/clutter-base-types.c |  168 ++++++++++++++++++++++++++++++++++++-----
 clutter/clutter-types.h      |   12 ++-
 clutter/clutter.symbols      |   10 ++-
 4 files changed, 196 insertions(+), 39 deletions(-)
---
diff --git a/clutter/clutter-actor-box.c b/clutter/clutter-actor-box.c
index 0a7f156..5389176 100644
--- a/clutter/clutter-actor-box.c
+++ b/clutter/clutter-actor-box.c
@@ -16,10 +16,18 @@
  * @y_2: Y coordinate of the bottom right point
  *
  * Allocates a new #ClutterActorBox using the passed coordinates
- * for the top left and bottom right points
+ * for the top left and bottom right points.
  *
- * Return value: the newly allocated #ClutterActorBox. Use
- *   clutter_actor_box_free() to free the resources
+ * This function is the logical equivalent of:
+ *
+ * |[
+ *   clutter_actor_box_init (clutter_actor_box_alloc (),
+ *                           x_1, y_1,
+ *                           x_2, y_2);
+ * ]|
+ *
+ * Return value: (transfer full): the newly allocated #ClutterActorBox.
+ *   Use clutter_actor_box_free() to free the resources
  *
  * Since: 1.0
  */
@@ -29,12 +37,25 @@ clutter_actor_box_new (gfloat x_1,
                        gfloat x_2,
                        gfloat y_2)
 {
-  ClutterActorBox *box;
-
-  box = g_slice_new (ClutterActorBox);
-  clutter_actor_box_init (box, x_1, y_1, x_2, y_2);
+  return clutter_actor_box_init (clutter_actor_box_alloc (),
+                                 x_1, y_1,
+                                 x_2, y_2);
+}
 
-  return box;
+/**
+ * clutter_actor_box_alloc:
+ *
+ * Allocates a new #ClutterActorBox.
+ *
+ * Return value: (transfer full): the newly allocated #ClutterActorBox.
+ *   Use clutter_actor_box_free() to free its resources
+ *
+ * Since: 1.12
+ */
+ClutterActorBox *
+clutter_actor_box_alloc (void)
+{
+  return g_slice_new0 (ClutterActorBox);
 }
 
 /**
@@ -47,21 +68,25 @@ clutter_actor_box_new (gfloat x_1,
  *
  * Initializes @box with the given coordinates.
  *
+ * Return value: (transfer none): the initialized #ClutterActorBox
+ *
  * Since: 1.10
  */
-void
+ClutterActorBox *
 clutter_actor_box_init (ClutterActorBox *box,
                         gfloat           x_1,
                         gfloat           y_1,
                         gfloat           x_2,
                         gfloat           y_2)
 {
-  g_return_if_fail (box != NULL);
+  g_return_val_if_fail (box != NULL, NULL);
 
   box->x1 = x_1;
   box->y1 = y_1;
   box->x2 = x_2;
   box->y2 = y_2;
+
+  return box;
 }
 
 /**
diff --git a/clutter/clutter-base-types.c b/clutter/clutter-base-types.c
index 8a91b6e..f95beda 100644
--- a/clutter/clutter-base-types.c
+++ b/clutter/clutter-base-types.c
@@ -156,10 +156,16 @@ G_DEFINE_BOXED_TYPE_WITH_CODE (ClutterGeometry, clutter_geometry,
  * @z: Z coordinate
  *
  * Creates a new #ClutterVertex for the point in 3D space
- * identified by the 3 coordinates @x, @y, @z
+ * identified by the 3 coordinates @x, @y, @z.
  *
- * Return value: the newly allocate #ClutterVertex. Use
- *   clutter_vertex_free() to free the resources
+ * This function is the logical equivalent of:
+ *
+ * |[
+ *   clutter_vertex_init (clutter_vertex_alloc (), x, y, z);
+ * ]|
+ *
+ * Return value: (transfer full): the newly allocated #ClutterVertex.
+ *   Use clutter_vertex_free() to free the resources
  *
  * Since: 1.0
  */
@@ -168,12 +174,23 @@ clutter_vertex_new (gfloat x,
                     gfloat y,
                     gfloat z)
 {
-  ClutterVertex *vertex;
-
-  vertex = g_slice_new (ClutterVertex);
-  clutter_vertex_init (vertex, x, y, z);
+  return clutter_vertex_init (clutter_vertex_alloc (), x, y, z);
+}
 
-  return vertex;
+/**
+ * clutter_vertex_alloc:
+ *
+ * Allocates a new, empty #ClutterVertex.
+ *
+ * Return value: (transfer full): the newly allocated #ClutterVertex.
+ *   Use clutter_vertex_free() to free its resources
+ *
+ * Since: 1.12
+ */
+ClutterVertex *
+clutter_vertex_alloc (void)
+{
+  return g_slice_new0 (ClutterVertex);
 }
 
 /**
@@ -185,19 +202,23 @@ clutter_vertex_new (gfloat x,
  *
  * Initializes @vertex with the given coordinates.
  *
+ * Return value: (transfer none): the initialized #ClutterVertex
+ *
  * Since: 1.10
  */
-void
+ClutterVertex *
 clutter_vertex_init (ClutterVertex *vertex,
                      gfloat         x,
                      gfloat         y,
                      gfloat         z)
 {
-  g_return_if_fail (vertex != NULL);
+  g_return_val_if_fail (vertex != NULL, NULL);
 
   vertex->x = x;
   vertex->y = y;
   vertex->z = z;
+
+  return vertex;
 }
 
 /**
@@ -206,8 +227,8 @@ clutter_vertex_init (ClutterVertex *vertex,
  *
  * Copies @vertex
  *
- * Return value: a newly allocated copy of #ClutterVertex. Use
- *   clutter_vertex_free() to free the allocated resources
+ * Return value: (transfer full): a newly allocated copy of #ClutterVertex.
+ *   Use clutter_vertex_free() to free the allocated resources
  *
  * Since: 1.0
  */
@@ -224,7 +245,8 @@ clutter_vertex_copy (const ClutterVertex *vertex)
  * clutter_vertex_free:
  * @vertex: a #ClutterVertex
  *
- * Frees a #ClutterVertex allocated using clutter_vertex_copy()
+ * Frees a #ClutterVertex allocated using clutter_vertex_alloc() or
+ * clutter_vertex_copy().
  *
  * Since: 1.0
  */
@@ -268,7 +290,7 @@ clutter_vertex_progress (const GValue *a,
 {
   const ClutterVertex *av = g_value_get_boxed (a);
   const ClutterVertex *bv = g_value_get_boxed (b);
-  ClutterVertex res = { 0, };
+  ClutterVertex res;
 
   res.x = av->x + (bv->x - av->x) * progress;
   res.y = av->y + (bv->y - av->y) * progress;
@@ -353,12 +375,34 @@ G_DEFINE_BOXED_TYPE (ClutterMargin, clutter_margin,
  * ClutterPoint
  */
 
+/**
+ * clutter_point_alloc:
+ *
+ * Allocates a new #ClutterPoint.
+ *
+ * Return value: (transfer full): the newly allocated #ClutterPoint.
+ *   Use clutter_point_free() to free its resources.
+ *
+ * Since: 1.12
+ */
 ClutterPoint *
-clutter_point_new (void)
+clutter_point_alloc (void)
 {
   return g_slice_new0 (ClutterPoint);
 }
 
+/**
+ * clutter_point_init:
+ * @point: a #ClutterPoint
+ * @x: the X coordinate of the point
+ * @y: the Y coordinate of the point
+ *
+ * Initializes @point with the given coordinates.
+ *
+ * Return value: (transfer none): the initialized #ClutterPoint
+ *
+ * Since: 1.12
+ */
 ClutterPoint *
 clutter_point_init (ClutterPoint *point,
                     float         x,
@@ -372,12 +416,31 @@ clutter_point_init (ClutterPoint *point,
   return point;
 }
 
+/**
+ * clutter_point_copy:
+ * @point: a #ClutterPoint
+ *
+ * Creates a new #ClutterPoint with the same coordinates of @point.
+ *
+ * Return value: (transfer full): a newly allocated #ClutterPoint.
+ *   Use clutter_point_free() to free its resources.
+ *
+ * Since: 1.12
+ */
 ClutterPoint *
 clutter_point_copy (const ClutterPoint *point)
 {
   return g_slice_dup (ClutterPoint, point);
 }
 
+/**
+ * clutter_point_free:
+ * @point: a #ClutterPoint
+ *
+ * Frees the resources allocated for @point.
+ *
+ * Since: 1.12
+ */
 void
 clutter_point_free (ClutterPoint *point)
 {
@@ -385,6 +448,17 @@ clutter_point_free (ClutterPoint *point)
     g_slice_free (ClutterPoint, point);
 }
 
+/**
+ * clutter_point_equals:
+ * @a: the first #ClutterPoint to compare
+ * @b: the second #ClutterPoint to compare
+ *
+ * Compares two #ClutterPoint for equality.
+ *
+ * Return value: %TRUE if the #ClutterPoints are equal
+ *
+ * Since: 1.12
+ */
 gboolean
 clutter_point_equals (const ClutterPoint *a,
                       const ClutterPoint *b)
@@ -427,12 +501,34 @@ G_DEFINE_BOXED_TYPE_WITH_CODE (ClutterPoint, clutter_point,
  * ClutterSize
  */
 
+/**
+ * clutter_size_alloc:
+ *
+ * Allocates a new #ClutterSize.
+ *
+ * Return value: (transfer full): the newly allocated #ClutterSize.
+ *   Use clutter_size_free() to free its resources.
+ *
+ * Since: 1.12
+ */
 ClutterSize *
-clutter_size_new (void)
+clutter_size_alloc (void)
 {
   return g_slice_new0 (ClutterSize);
 }
 
+/**
+ * clutter_size_init:
+ * @size: a #ClutterSize
+ * @width: the width
+ * @height: the height
+ *
+ * Initializes a #ClutterSize with the given dimensions.
+ *
+ * Return value: (transfer none): the initialized #ClutterSize
+ *
+ * Since: 1.12
+ */
 ClutterSize *
 clutter_size_init (ClutterSize *size,
                    float        width,
@@ -446,12 +542,31 @@ clutter_size_init (ClutterSize *size,
   return size;
 }
 
+/**
+ * clutter_size_copy:
+ * @size: a #ClutterSize
+ *
+ * Creates a new #ClutterSize and duplicates @size.
+ *
+ * Return value: (transfer full): the newly allocated #ClutterSize.
+ *   Use clutter_size_free() to free its resources.
+ *
+ * Since: 1.12
+ */
 ClutterSize *
 clutter_size_copy (const ClutterSize *size)
 {
   return g_slice_dup (ClutterSize, size);
 }
 
+/**
+ * clutter_size_free:
+ * @size: a #ClutterSize
+ *
+ * Frees the resources allocated for @size.
+ *
+ * Since: 1.12
+ */
 void
 clutter_size_free (ClutterSize *size)
 {
@@ -459,6 +574,17 @@ clutter_size_free (ClutterSize *size)
     g_slice_free (ClutterSize, size);
 }
 
+/**
+ * clutter_size_equals:
+ * @a: a #ClutterSize to compare
+ * @b: a #ClutterSize to compare
+ *
+ * Compares two #ClutterSize for equality.
+ *
+ * Return value: %TRUE if the two #ClutterSize are equal
+ *
+ * Since: 1.12
+ */
 gboolean
 clutter_size_equals (const ClutterSize *a,
                      const ClutterSize *b)
@@ -535,7 +661,7 @@ clutter_rect_normalize_internal (ClutterRect *rect)
 }
 
 /**
- * clutter_rect_new:
+ * clutter_rect_alloc:
  *
  * Creates a new, empty #ClutterRect.
  *
@@ -543,9 +669,7 @@ clutter_rect_normalize_internal (ClutterRect *rect)
  * for instance:
  *
  * |[
- *   ClutterRect *rect;
- *
- *   rect = clutter_rect_init (clutter_rect_new (), x, y, width, height);
+ *   rect = clutter_rect_init (clutter_rect_alloc (), x, y, width, height);
  * ]|
  *
  * Return value: (transfer full): the newly allocated #ClutterRect.
@@ -554,7 +678,7 @@ clutter_rect_normalize_internal (ClutterRect *rect)
  * Since: 1.12
  */
 ClutterRect *
-clutter_rect_new (void)
+clutter_rect_alloc (void)
 {
   return g_slice_new0 (ClutterRect);
 }
@@ -1021,6 +1145,8 @@ clutter_rect_progress (const GValue *a,
 
 #undef INTERPOLATE
 
+  clutter_rect_normalize_internal (&res);
+
   g_value_set_boxed (retval, &res);
 
   return TRUE;
diff --git a/clutter/clutter-types.h b/clutter/clutter-types.h
index 07c47ab..4c5e370 100644
--- a/clutter/clutter-types.h
+++ b/clutter/clutter-types.h
@@ -131,7 +131,7 @@ struct _ClutterPoint
 
 GType clutter_point_get_type (void) G_GNUC_CONST;
 
-ClutterPoint *  clutter_point_new       (void);
+ClutterPoint *  clutter_point_alloc     (void);
 ClutterPoint *  clutter_point_init      (ClutterPoint       *point,
                                          float               x,
                                          float               y);
@@ -160,7 +160,7 @@ struct _ClutterSize
 
 GType clutter_size_get_type (void) G_GNUC_CONST;
 
-ClutterSize *   clutter_size_new        (void);
+ClutterSize *   clutter_size_alloc      (void);
 ClutterSize *   clutter_size_init       (ClutterSize       *size,
                                          float              width,
                                          float              height);
@@ -201,7 +201,7 @@ struct _ClutterRect
 
 GType clutter_rect_get_type (void) G_GNUC_CONST;
 
-ClutterRect *   clutter_rect_new                (void);
+ClutterRect *   clutter_rect_alloc              (void);
 ClutterRect *   clutter_rect_init               (ClutterRect       *rect,
                                                  float              x,
                                                  float              y,
@@ -272,7 +272,8 @@ GType          clutter_vertex_get_type (void) G_GNUC_CONST;
 ClutterVertex *clutter_vertex_new      (gfloat               x,
                                         gfloat               y,
                                         gfloat               z);
-void           clutter_vertex_init     (ClutterVertex       *vertex,
+ClutterVertex *clutter_vertex_alloc    (void);
+ClutterVertex *clutter_vertex_init     (ClutterVertex       *vertex,
                                         gfloat               x,
                                         gfloat               y,
                                         gfloat               z);
@@ -324,7 +325,8 @@ ClutterActorBox *clutter_actor_box_new           (gfloat                 x_1,
                                                   gfloat                 y_1,
                                                   gfloat                 x_2,
                                                   gfloat                 y_2);
-void             clutter_actor_box_init          (ClutterActorBox       *box,
+ClutterActorBox *clutter_actor_box_alloc         (void);
+ClutterActorBox *clutter_actor_box_init          (ClutterActorBox       *box,
                                                   gfloat                 x_1,
                                                   gfloat                 y_1,
                                                   gfloat                 x_2,
diff --git a/clutter/clutter.symbols b/clutter/clutter.symbols
index 4f93ba9..588b022 100644
--- a/clutter/clutter.symbols
+++ b/clutter/clutter.symbols
@@ -44,6 +44,7 @@ clutter_actor_animate_with_timeline
 clutter_actor_animate_with_timelinev
 clutter_actor_apply_transform_to_point
 clutter_actor_apply_relative_transform_to_point
+clutter_actor_box_alloc
 clutter_actor_box_clamp_to_pixel
 clutter_actor_box_contains
 clutter_actor_box_copy
@@ -530,6 +531,7 @@ clutter_colorize_effect_get_type
 clutter_colorize_effect_new
 clutter_colorize_effect_set_tint
 clutter_color_add
+clutter_color_alloc
 clutter_color_copy
 clutter_color_darken
 clutter_color_equal
@@ -540,6 +542,7 @@ clutter_color_from_string
 clutter_color_get_static
 clutter_color_get_type
 clutter_color_hash
+clutter_color_init
 clutter_color_interpolate
 clutter_color_lighten
 clutter_color_new
@@ -977,17 +980,18 @@ clutter_pick_debug_flags DATA
 clutter_pipeline_node_get_type
 clutter_pipeline_node_new
 clutter_pick_mode_get_type
+clutter_point_alloc
 clutter_point_copy
 clutter_point_equals
 clutter_point_free
 clutter_point_get_type
 clutter_point_init
-clutter_point_new
 clutter_profile_flags DATA
 clutter_property_transition_get_property_name
 clutter_property_transition_get_type
 clutter_property_transition_new
 clutter_property_transition_set_property_name
+clutter_rect_alloc
 clutter_rect_clamp_to_pixel
 clutter_rect_contains_point
 clutter_rect_copy
@@ -1002,7 +1006,6 @@ clutter_rect_get_y
 clutter_rect_init
 clutter_rect_inset
 clutter_rect_intersection
-clutter_rect_new
 clutter_rect_normalize
 clutter_rect_offset
 clutter_rect_union
@@ -1095,12 +1098,12 @@ clutter_shader_set_is_enabled
 clutter_shader_set_uniform
 clutter_shader_set_vertex_source
 clutter_shader_type_get_type
+clutter_size_alloc
 clutter_size_copy
 clutter_size_equals
 clutter_size_free
 clutter_size_get_type
 clutter_size_init
-clutter_size_new
 clutter_snap_constraint_get_edges
 clutter_snap_constraint_get_offset
 clutter_snap_constraint_get_source
@@ -1443,6 +1446,7 @@ clutter_value_set_shader_int
 clutter_value_set_shader_matrix
 clutter_value_set_units
 clutter_value_take_paint_node
+clutter_vertex_alloc
 clutter_vertex_copy
 clutter_vertex_equal
 clutter_vertex_free
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]