glib/gbuffer.h

   1 /*
   2  * Copyright © 2009, 2010 Codethink Limited
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the licence, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Author: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #ifndef __G_BUFFER_H__
  23 #define __G_BUFFER_H__
  24
  25 #include <glib/gtypes.h>
  26
  27 /* < private >
  28  * GBuffer:
  29  * @data: a pointer to the data held in the buffer
  30  * @size: the size of @data
  31  *
  32  * A simple refcounted data type representing a byte sequence from an
  33  * unspecified origin.
  34  *
  35  * The purpose of a #GBuffer is to keep the memory region that it holds
  36  * alive for as long as anyone holds a reference to the buffer.  When
  37  * the last reference count is dropped, the memory is released.
  38  *
  39  * A #GBuffer can come from many different origins that may have
  40  * different procedures for freeing the memory region.  Examples are
  41  * memory from g_malloc(), from memory slices, from a #GMappedFile or
  42  * memory from other allocators.
  43  */
  44 typedef struct _GBuffer GBuffer;
  45
  46 /* < private >
  47  * GBufferFreeFunc:
  48  * @buffer: the #GBuffer to be freed
  49  *
  50  * This function is provided by creators of a #GBuffer.  It is the
  51  * function to be called when the reference count of @buffer drops to
  52  * zero.  It should free any memory associated with the buffer and free
  53  * @buffer itself.
  54  */
  55 typedef void (* GBufferFreeFunc)                (GBuffer        *buffer);
  56
  57 struct _GBuffer
  58 {
  59   gconstpointer data;
  60   gsize size;
  61
  62   /*< protected >*/
  63   GBufferFreeFunc free_func;
  64
  65   /*< private >*/
  66   gint ref_count;
  67 };
  68
  69 G_GNUC_INTERNAL
  70 GBuffer *       g_buffer_new_from_data          (gconstpointer   data,
  71                                                  gsize           size);
  72 G_GNUC_INTERNAL
  73 GBuffer *       g_buffer_new_take_data          (gpointer        data,
  74                                                  gsize           size);
  75 G_GNUC_INTERNAL
  76 GBuffer *       g_buffer_new_from_static_data   (gconstpointer   data,
  77                                                  gsize           size);
  78 G_GNUC_INTERNAL
  79 GBuffer *       g_buffer_new_from_pointer       (gconstpointer   data,
  80                                                  gsize           size,
  81                                                  GDestroyNotify  notify,
  82                                                  gpointer        user_data);
  83 G_GNUC_INTERNAL
  84 GBuffer *     g_buffer_ref                      (GBuffer        *buffer);
  85 G_GNUC_INTERNAL
  86 void          g_buffer_unref                    (GBuffer        *buffer);
  87
  88 #endif /* __G_BUFFER_H__ */