1 /* PEAK Library 2 * 3 * Copyright (c) 2003 4 * Stephane Thiell <mbuna@bugged.org>. All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 21 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 22 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 23 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 24 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 25 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 26 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 27 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 * 29 * $Id: garbage.h,v 1.1.1.1 2003/12/30 02:29:14 mbuna Exp $ 30 */ 31 #ifndef INCLUDED_PEAK_GARBAGE_H_ 32 #define INCLUDED_PEAK_GARBAGE_H_ 33 34 /*! 35 * @defgroup garbage Garbage collector 36 * 37 * @par 38 * In brief: this module adds a feature to delay the destruction of pointers 39 * of different sizes, thus allowing the application to reuse some pointers 40 * not really deleted yet. See the \p mem_pool module for another type of 41 * allocation optimization feature. 42 * 43 * @par 44 * A simple garbage collector (with explicit collection) which provides 45 * asynchronous deletion. It is probably only useful when an application 46 * could avoid to recreate the same objects, when all objects are not of 47 * the same size. If it's better for you to just keep them a few seconds 48 * or minutes before really delete them, in case you want to reuse them, so 49 * this module is probably for you. When it's time to really delete an object, 50 * the library calls your callback: if the object has been reused since, just 51 * ignore the call... or really delete it otherwise. 52 * 53 * @par 54 * This module has been created in order to optimize allocations of IRC 55 * channels, which are allocated structures of different sizes (different 56 * names) and commonly deleted and re-allocated just after (part/join of an 57 * empty channel). I am not sure it will suit for something else. 58 * 59 * @par 60 * Usage is very easy: initialize a garbage collector object with 61 * peak_garbage_create() providing a generic deletion callback for all 62 * collected objects, then call peak_garbage_collect() for each object you 63 * want to delete using the collector. The objects will be automatically 64 * deleted (you shouldn't predict the deletion, as the frequency is only a 65 * hint - note it's usually less because all collected objects are always 66 * deleted at the same time). If needed, you can force all objects deletion 67 * with the peak_garbage_vacuum() function. 68 */ 69 70 #include <peak/task.h> 71 72 /*! 73 * @ingroup garbage 74 * @brief Opaque garbage collector pointer type. 75 */ 76 typedef struct __peak_garbage * peak_garbage; 77 78 /*! 79 * @ingroup garbage 80 * @brief Deletion's callback definition. 81 */ 82 typedef void (*peak_garbage_callback)(peak_garbage g, void *ptr, 83 void *context); 84 85 #if defined(__cplusplus) 86 extern "C" { 87 #endif 88 89 /*! 90 * @ingroup garbage 91 * @brief Create a garbage object. 92 * 93 * @param max_ptrs Max pointers that the garbage object can collect at the 94 * same time. Must be strictly positive. If reached, a 95 * vacuuming is performed and the object properly collected. 96 * @param frequency Frequency hint in seconds at which you want to do the 97 * vacuuming (deletions), it's usually less because when 98 * vacuuming the callback is called for all objects already 99 * collected. 100 * @param task Task to schedule, can be \p NULL to use current task. 101 * @param callout A pointer to your deletion callback function which is 102 * triggered when automatic of manual vacuuming. 103 * @param context An extra application-defined pointer that will be passed 104 * to your garbage callback function. 105 * 106 * @return A newly allocated \p peak_garbage reference or \p NULL 107 * if the object cannot be created. 108 */ 109 extern peak_garbage peak_garbage_create( 110 int max_ptrs, 111 double frequency, 112 peak_task task, 113 peak_garbage_callback callout, 114 void *context 115 ); 116 117 /*! 118 * @ingroup garbage 119 * @brief Collect a pointer and schedules the garbage's task for deletion. 120 * 121 * Guaranteed O(1) unless \a max_ptrs is reached. 122 * 123 * @param g The garbage object reference. 124 * @param ptr Pointer to collect for deletion. 125 */ 126 extern void peak_garbage_collect( 127 peak_garbage g, 128 void *ptr 129 ); 130 131 /*! 132 * @ingroup garbage 133 * @brief Get the current number of pointers collected for deletion. 134 * 135 * @param g The garbage object reference. 136 * 137 * @return Collected pointers count. 138 */ 139 extern int peak_garbage_get_collected_count( 140 peak_garbage g 141 ); 142 143 /*! 144 * @ingroup garbage 145 * @brief Perform manual vacuuming. 146 * 147 * @param g The garbage object reference. 148 */ 149 extern void peak_garbage_vacuum( 150 peak_garbage g 151 ); 152 153 154 #if defined(__cplusplus) 155 } 156 #endif 157 158 #endif /* INCLUDED_PEAK_GARBAGE_H_ */ 159