src/page.h

   1 /*
   2  * Copyright (C) 2003-2010 The Music Player Daemon Project
   3  * http://www.musicpd.org
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  */
  19
  20 /** \file
  21  *
  22  * This is a library which manages reference counted buffers.
  23  */
  24
  25 #ifndef MPD_PAGE_H
  26 #define MPD_PAGE_H
  27
  28 #include <stddef.h>
  29 #include <stdbool.h>
  30
  31 /**
  32  * A dynamically allocated buffer which keeps track of its reference
  33  * count.  This is useful for passing buffers around, when several
  34  * instances hold references to one buffer.
  35  */
  36 struct page {
  37         /**
  38          * The number of references to this buffer.  This library uses
  39          * atomic functions to access it, i.e. no locks are required.
  40          * As soon as this attribute reaches zero, the buffer is
  41          * freed.
  42          */
  43         int ref;
  44
  45         /**
  46          * The size of this buffer in bytes.
  47          */
  48         size_t size;
  49
  50         /**
  51          * Dynamic array containing the buffer data.
  52          */
  53         unsigned char data[sizeof(long)];
  54 };
  55
  56 /**
  57  * Creates a new #page object, and copies data from the specified
  58  * buffer.  It is initialized with a reference count of 1.
  59  *
  60  * @param data the source buffer
  61  * @param size the size of the source buffer
  62  * @return the new #page object
  63  */
  64 struct page *
  65 page_new_copy(const void *data, size_t size);
  66
  67 /**
  68  * Concatenates two pages to a new page.
  69  *
  70  * @param a the first page
  71  * @param b the second page, which is appended
  72  */
  73 struct page *
  74 page_new_concat(const struct page *a, const struct page *b);
  75
  76 /**
  77  * Increases the reference counter.
  78  *
  79  * @param page the #page object
  80  */
  81 void
  82 page_ref(struct page *page);
  83
  84 /**
  85  * Decreases the reference counter.  If it reaches zero, the #page is
  86  * freed.
  87  *
  88  * @param page the #page object
  89  * @return true if the #page has been freed
  90  */
  91 bool
  92 page_unref(struct page *page);
  93
  94 #endif