| 1 |
\hypertarget{group__garbage}{ |
| 2 |
\section{Garbage collector} |
| 3 |
\label{group__garbage}\index{Garbage collector@{Garbage collector}} |
| 4 |
} |
| 5 |
|
| 6 |
|
| 7 |
\subsection{Detailed Description} |
| 8 |
\begin{Desc} |
| 9 |
\item[]In brief: this module adds a feature to delay the destruction of pointers of different sizes, thus allowing the application to reuse some pointers not really deleted yet. See the {\tt mem\_\-pool} module for another type of allocation optimization feature.\end{Desc} |
| 10 |
\begin{Desc} |
| 11 |
\item[]A simple garbage collector (with explicit collection) which provides asynchronous deletion. It is probably only useful when an application could avoid to recreate the same objects, when all objects are not of the same size. If it's better for you to just keep them a few seconds or minutes before really delete them, in case you want to reuse them, so this module is probably for you. When it's time to really delete an object, the library calls your callback: if the object has been reused since, just ignore the call... or really delete it otherwise.\end{Desc} |
| 12 |
\begin{Desc} |
| 13 |
\item[]This module has been created in order to optimize allocations of IRC channels, which are allocated structures of different sizes (different names) and commonly deleted and re-allocated just after (part/join of an empty channel). I am not sure it will suit for something else.\end{Desc} |
| 14 |
\begin{Desc} |
| 15 |
\item[]Usage is very easy: initialize a garbage collector object with \hyperlink{group__garbage_ga9}{peak\_\-garbage\_\-create()} providing a generic deletion callback for all collected objects, then call \hyperlink{group__garbage_ga10}{peak\_\-garbage\_\-collect()} for each object you want to delete using the collector. The objects will be automatically deleted (you shouldn't predict the deletion, as the frequency is only a hint - note it's usually less because all collected objects are always deleted at the same time). If needed, you can force all objects deletion with the \hyperlink{group__garbage_ga12}{peak\_\-garbage\_\-vacuum()} function. \end{Desc} |
| 16 |
|
| 17 |
|
| 18 |
\subsection*{Typedefs} |
| 19 |
\begin{CompactItemize} |
| 20 |
\item |
| 21 |
\hypertarget{group__garbage_ga0}{ |
| 22 |
typedef \_\-\_\-peak\_\-garbage $\ast$ \hyperlink{group__garbage_ga0}{peak\_\-garbage}} |
| 23 |
\label{group__garbage_ga0} |
| 24 |
|
| 25 |
\begin{CompactList}\small\item\em Opaque garbage collector pointer type. \item\end{CompactList}\item |
| 26 |
\hypertarget{group__garbage_ga1}{ |
| 27 |
typedef void($\ast$ \hyperlink{group__garbage_ga1}{peak\_\-garbage\_\-callback} )(\hyperlink{group__garbage_ga0}{peak\_\-garbage} g, void $\ast$ptr, void $\ast$context)} |
| 28 |
\label{group__garbage_ga1} |
| 29 |
|
| 30 |
\begin{CompactList}\small\item\em Deletion's callback definition. \item\end{CompactList}\end{CompactItemize} |
| 31 |
\subsection*{Functions} |
| 32 |
\begin{CompactItemize} |
| 33 |
\item |
| 34 |
\hyperlink{group__garbage_ga0}{peak\_\-garbage} \hyperlink{group__garbage_ga2}{peak\_\-garbage\_\-create} (int max\_\-ptrs, double frequency, \hyperlink{group__task__common_ga0}{peak\_\-task} task, \hyperlink{group__garbage_ga1}{peak\_\-garbage\_\-callback} callout, void $\ast$context) |
| 35 |
\begin{CompactList}\small\item\em Create a garbage object. \item\end{CompactList}\item |
| 36 |
void \hyperlink{group__garbage_ga3}{peak\_\-garbage\_\-collect} (\hyperlink{group__garbage_ga0}{peak\_\-garbage} g, void $\ast$ptr) |
| 37 |
\begin{CompactList}\small\item\em Collect a pointer and schedules the garbage's task for deletion. \item\end{CompactList}\item |
| 38 |
int \hyperlink{group__garbage_ga4}{peak\_\-garbage\_\-get\_\-collected\_\-count} (\hyperlink{group__garbage_ga0}{peak\_\-garbage} g) |
| 39 |
\begin{CompactList}\small\item\em Get the current number of pointers collected for deletion. \item\end{CompactList}\item |
| 40 |
void \hyperlink{group__garbage_ga5}{peak\_\-garbage\_\-vacuum} (\hyperlink{group__garbage_ga0}{peak\_\-garbage} g) |
| 41 |
\begin{CompactList}\small\item\em Perform manual vacuuming. \item\end{CompactList}\end{CompactItemize} |
| 42 |
|
| 43 |
|
| 44 |
\subsection{Function Documentation} |
| 45 |
\hypertarget{group__garbage_ga3}{ |
| 46 |
\index{garbage@{garbage}!peak_garbage_collect@{peak\_\-garbage\_\-collect}} |
| 47 |
\index{peak_garbage_collect@{peak\_\-garbage\_\-collect}!garbage@{garbage}} |
| 48 |
\subsubsection[peak\_\-garbage\_\-collect]{\setlength{\rightskip}{0pt plus 5cm}void peak\_\-garbage\_\-collect (\hyperlink{group__garbage_ga0}{peak\_\-garbage} {\em g}, void $\ast$ {\em ptr})}} |
| 49 |
\label{group__garbage_ga3} |
| 50 |
|
| 51 |
|
| 52 |
Collect a pointer and schedules the garbage's task for deletion. |
| 53 |
|
| 54 |
Guaranteed O(1) unless {\em max\_\-ptrs\/} is reached. |
| 55 |
|
| 56 |
\begin{Desc} |
| 57 |
\item[Parameters:] |
| 58 |
\begin{description} |
| 59 |
\item[{\em g}]The garbage object reference. \item[{\em ptr}]Pointer to collect for deletion. \end{description} |
| 60 |
\end{Desc} |
| 61 |
\hypertarget{group__garbage_ga2}{ |
| 62 |
\index{garbage@{garbage}!peak_garbage_create@{peak\_\-garbage\_\-create}} |
| 63 |
\index{peak_garbage_create@{peak\_\-garbage\_\-create}!garbage@{garbage}} |
| 64 |
\subsubsection[peak\_\-garbage\_\-create]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{group__garbage_ga0}{peak\_\-garbage} peak\_\-garbage\_\-create (int {\em max\_\-ptrs}, double {\em frequency}, \hyperlink{group__task__common_ga0}{peak\_\-task} {\em task}, \hyperlink{group__garbage_ga1}{peak\_\-garbage\_\-callback} {\em callout}, void $\ast$ {\em context})}} |
| 65 |
\label{group__garbage_ga2} |
| 66 |
|
| 67 |
|
| 68 |
Create a garbage object. |
| 69 |
|
| 70 |
\begin{Desc} |
| 71 |
\item[Parameters:] |
| 72 |
\begin{description} |
| 73 |
\item[{\em max\_\-ptrs}]Max pointers that the garbage object can collect at the same time. Must be strictly positive. If reached, a vacuuming is performed and the object properly collected. \item[{\em frequency}]Frequency hint in seconds at which you want to do the vacuuming (deletions), it's usually less because when vacuuming the callback is called for all objects already collected. \item[{\em task}]Task to schedule, can be {\tt NULL} to use current task. \item[{\em callout}]A pointer to your deletion callback function which is triggered when automatic of manual vacuuming. \item[{\em context}]An extra application-defined pointer that will be passed to your garbage callback function.\end{description} |
| 74 |
\end{Desc} |
| 75 |
\begin{Desc} |
| 76 |
\item[Returns:]A newly allocated {\tt peak\_\-garbage} reference or {\tt NULL} if the object cannot be created. \end{Desc} |
| 77 |
\hypertarget{group__garbage_ga4}{ |
| 78 |
\index{garbage@{garbage}!peak_garbage_get_collected_count@{peak\_\-garbage\_\-get\_\-collected\_\-count}} |
| 79 |
\index{peak_garbage_get_collected_count@{peak\_\-garbage\_\-get\_\-collected\_\-count}!garbage@{garbage}} |
| 80 |
\subsubsection[peak\_\-garbage\_\-get\_\-collected\_\-count]{\setlength{\rightskip}{0pt plus 5cm}int peak\_\-garbage\_\-get\_\-collected\_\-count (\hyperlink{group__garbage_ga0}{peak\_\-garbage} {\em g})}} |
| 81 |
\label{group__garbage_ga4} |
| 82 |
|
| 83 |
|
| 84 |
Get the current number of pointers collected for deletion. |
| 85 |
|
| 86 |
\begin{Desc} |
| 87 |
\item[Parameters:] |
| 88 |
\begin{description} |
| 89 |
\item[{\em g}]The garbage object reference.\end{description} |
| 90 |
\end{Desc} |
| 91 |
\begin{Desc} |
| 92 |
\item[Returns:]Collected pointers count. \end{Desc} |
| 93 |
\hypertarget{group__garbage_ga5}{ |
| 94 |
\index{garbage@{garbage}!peak_garbage_vacuum@{peak\_\-garbage\_\-vacuum}} |
| 95 |
\index{peak_garbage_vacuum@{peak\_\-garbage\_\-vacuum}!garbage@{garbage}} |
| 96 |
\subsubsection[peak\_\-garbage\_\-vacuum]{\setlength{\rightskip}{0pt plus 5cm}void peak\_\-garbage\_\-vacuum (\hyperlink{group__garbage_ga0}{peak\_\-garbage} {\em g})}} |
| 97 |
\label{group__garbage_ga5} |
| 98 |
|
| 99 |
|
| 100 |
Perform manual vacuuming. |
| 101 |
|
| 102 |
\begin{Desc} |
| 103 |
\item[Parameters:] |
| 104 |
\begin{description} |
| 105 |
\item[{\em g}]The garbage object reference. \end{description} |
| 106 |
\end{Desc} |
