\doxysection{Use Counter}
\label{group__use__count}\index{Use Counter@{Use Counter}}


Generic object usage counter (get, put and deallocate on zero count).  


\doxysubsection*{Files}
\begin{DoxyCompactItemize}
\item 
file \textbf{ use\+\_\+count.\+h}
\begin{DoxyCompactList}\small\item\em Generic object usage counter API (get, put and deallocate on zero count). \end{DoxyCompactList}\item 
file \textbf{ use\+\_\+count.\+c}
\begin{DoxyCompactList}\small\item\em Generic object usage counter Implementation (get, put and deallocate on zero count). \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct \textbf{ osmo\+\_\+use\+\_\+count}
\begin{DoxyCompactList}\small\item\em Use counter state for one used object, managing N distinct named counters. \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry}
\begin{DoxyCompactList}\small\item\em One named counter in the list managed by \doxyref{osmo\+\_\+use\+\_\+count}{p.}{structosmo__use__count}. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \textbf{ osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put}(USE\+\_\+\+LIST,  USE,  CHANGE)~ \textbf{ \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put}(USE\+\_\+\+LIST, USE, CHANGE, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em Change the use count for a given use token. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ \textbf{ osmo\+\_\+use\+\_\+count\+\_\+cb\+\_\+t}) (struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$use\+\_\+count\+\_\+entry, int32\+\_\+t old\+\_\+use\+\_\+count, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Invoked when a use count changes. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \textbf{ \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put} (struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc, const char $\ast$use, int32\+\_\+t change, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Implementation for \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}, which can also be directly invoked to pass source file information. \end{DoxyCompactList}\item 
const char $\ast$ \textbf{ osmo\+\_\+use\+\_\+count\+\_\+name\+\_\+buf} (char $\ast$buf, size\+\_\+t buf\+\_\+len, const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc)
\begin{DoxyCompactList}\small\item\em Write a comprehensive listing of use counts to a string buffer. \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+buf} (char $\ast$buf, size\+\_\+t buf\+\_\+len, const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc)
\begin{DoxyCompactList}\small\item\em Write a comprehensive listing of use counts to a string buffer. \end{DoxyCompactList}\item 
char $\ast$ \textbf{ osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+c} (void $\ast$ctx, const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc)
\begin{DoxyCompactList}\small\item\em Write a comprehensive listing of use counts to a talloc allocated string buffer. \end{DoxyCompactList}\item 
int32\+\_\+t \textbf{ osmo\+\_\+use\+\_\+count\+\_\+total} (const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc)
\begin{DoxyCompactList}\small\item\em Return the sum of all use counts, min-\/ and max-\/clamped at INT32\+\_\+\+MIN and INT32\+\_\+\+MAX. \end{DoxyCompactList}\item 
int32\+\_\+t \textbf{ osmo\+\_\+use\+\_\+count\+\_\+by} (const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc, const char $\ast$use)
\begin{DoxyCompactList}\small\item\em Return use count by a single use token. \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$ \textbf{ osmo\+\_\+use\+\_\+count\+\_\+find} (const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc, const char $\ast$use)
\item 
void \textbf{ osmo\+\_\+use\+\_\+count\+\_\+free} (struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$use\+\_\+count\+\_\+entry)
\begin{DoxyCompactList}\small\item\em Deallocate a use count entry. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+use\+\_\+count\+\_\+make\+\_\+static\+\_\+entries} (struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc, struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$buf, size\+\_\+t buf\+\_\+n\+\_\+entries)
\begin{DoxyCompactList}\small\item\em Add N static use token entries to avoid dynamic allocation of use count tokens. \end{DoxyCompactList}\item 
static bool \textbf{ count\+\_\+safe} (int32\+\_\+t $\ast$val\+\_\+p, int32\+\_\+t add)
\begin{DoxyCompactList}\small\item\em Add two int32\+\_\+t but make sure to min-\/ and max-\/clamp at INT32\+\_\+\+MIN and INT32\+\_\+\+MAX, respectively. \end{DoxyCompactList}\item 
static struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$ \textbf{ osmo\+\_\+use\+\_\+count\+\_\+repurpose\+\_\+zero\+\_\+entry} (struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc, const char $\ast$use)
\begin{DoxyCompactList}\small\item\em Find a use count entry that currently has zero count, and re-\/use that for this new use token. \end{DoxyCompactList}\item 
static struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$ \textbf{ osmo\+\_\+use\+\_\+count\+\_\+create} (struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$uc, const char $\ast$use)
\begin{DoxyCompactList}\small\item\em Allocate a new use count entry, happens implicitly in \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Generic object usage counter (get, put and deallocate on zero count). 

For an example and a detailed description, see struct \doxyref{osmo\+\_\+use\+\_\+count}{p.}{structosmo__use__count}. 

\doxysubsection{Macro Definition Documentation}
\mbox{\label{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_get\_put@{osmo\_use\_count\_get\_put}}
\index{osmo\_use\_count\_get\_put@{osmo\_use\_count\_get\_put}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_get\_put}
{\footnotesize\ttfamily \#define osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put(\begin{DoxyParamCaption}\item[{}]{USE\+\_\+\+LIST,  }\item[{}]{USE,  }\item[{}]{CHANGE }\end{DoxyParamCaption})~ \textbf{ \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put}(USE\+\_\+\+LIST, USE, CHANGE, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)}



Change the use count for a given use token. 


\begin{DoxyParams}{Parameters}
{\em USE\+\_\+\+LIST} & A struct osmo\+\_\+use\+\_\+count$\ast$, e.\+g. \&my\+\_\+obj-\/$>$use\+\_\+count. \\
\hline
{\em USE} & A use token\+: arbitrary string (const char$\ast$). This must remain valid memory, e.\+g. string constants. \\
\hline
{\em CHANGE} & Signed integer value to add to the use count\+: positive means get(), negative means put(). \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Negative on range violations or USE\+\_\+\+LIST == NULL, the use\+\_\+cb()\textquotesingle{}s return value, or 0 on success. 
\end{DoxyReturn}


\doxysubsection{Typedef Documentation}
\mbox{\label{group__use__count_ga4497d9dc69e733d16d33a455d385931e}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_cb\_t@{osmo\_use\_count\_cb\_t}}
\index{osmo\_use\_count\_cb\_t@{osmo\_use\_count\_cb\_t}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_cb\_t}
{\footnotesize\ttfamily typedef int($\ast$ osmo\+\_\+use\+\_\+count\+\_\+cb\+\_\+t) (struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$use\+\_\+count\+\_\+entry, int32\+\_\+t old\+\_\+use\+\_\+count, const char $\ast$\textbf{ file}, int line)}



Invoked when a use count changes. 

The implementation is free to trigger actions on arbitrary use count changes, typically to free the use\+\_\+count-\/$>$talloc\+\_\+object when the total use count reaches zero.

The implementation may modify use\+\_\+count\+\_\+entry-\/$>$count, for example for handling of get()/put() bugs, to clamp specific use tokens to specific counts, or to prevent the caller from put()ting into negative counts. When returning an error, there is no implicit undo -- if errors need to be corrected, this function is responsible for that.

Be aware\+: use token strings are not copied, and use count entries usually remain listed also when they reach a zero count. This is trivially perfectly ok when using string literals as use tokens. It is also possible to use dynamically allocated string tokens, but should a use token string become invalid memory when reaching zero count, it is the responsibility of this function to set the use\+\_\+count\+\_\+entry-\/$>$use = NULL; this is required to avoid subsequent \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233} invocations from calling strcmp() on invalid memory. (Setting use = NULL cannot be done implicitly after this callback invocation, because callback implementations are allowed to completely deallocate the talloc\+\_\+object and the use\+\_\+count list entries, and setting use = NULL after that would be a use-\/after-\/free.)


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em use\+\_\+count\+\_\+entry} & Use count entry that is being modified. \\
\hline
\mbox{\texttt{ in}}  & {\em old\+\_\+use\+\_\+count} & Use count the item had before the change in use count. \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Source file string, passed in as {\bfseries{FILE}} from macro \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}. \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Source file line, passed in as {\bfseries{LINE}} from macro \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success, negative if any undesired use count is reached; this rc will be returned by \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}. 
\end{DoxyReturn}


\doxysubsection{Function Documentation}
\mbox{\label{group__use__count_gad3fc149e66e6f9157843169f27ce571a}} 
\index{Use Counter@{Use Counter}!\_osmo\_use\_count\_get\_put@{\_osmo\_use\_count\_get\_put}}
\index{\_osmo\_use\_count\_get\_put@{\_osmo\_use\_count\_get\_put}!Use Counter@{Use Counter}}
\doxysubsubsection{\_osmo\_use\_count\_get\_put()}
{\footnotesize\ttfamily int \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc,  }\item[{const char $\ast$}]{use,  }\item[{int32\+\_\+t}]{change,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



Implementation for \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}, which can also be directly invoked to pass source file information. 

For arguments besides file and line, see \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}. 
\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em file} & Source file path, as in {\bfseries{FILE}}. \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Source file line, as in {\bfseries{LINE}}. \\
\hline
\end{DoxyParams}


References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::count}, \textbf{ count\+\_\+safe()}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, \textbf{ file()}, \textbf{ llist\+\_\+add\+\_\+tail()}, \textbf{ llist\+\_\+del()}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+create()}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+find()}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+repurpose\+\_\+zero\+\_\+entry()}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use}, \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+cb}, and \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+counts}.

\mbox{\label{group__use__count_gaf2aa74b203011c4359eb13cb886beae7}} 
\index{Use Counter@{Use Counter}!count\_safe@{count\_safe}}
\index{count\_safe@{count\_safe}!Use Counter@{Use Counter}}
\doxysubsubsection{count\_safe()}
{\footnotesize\ttfamily static bool count\+\_\+safe (\begin{DoxyParamCaption}\item[{int32\+\_\+t $\ast$}]{val\+\_\+p,  }\item[{int32\+\_\+t}]{add }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}



Add two int32\+\_\+t but make sure to min-\/ and max-\/clamp at INT32\+\_\+\+MIN and INT32\+\_\+\+MAX, respectively. 



Referenced by \textbf{ \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}, and \textbf{ osmo\+\_\+use\+\_\+count\+\_\+total()}.

\mbox{\label{group__use__count_gae221053a7e938cc89864a29cd72bb971}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_by@{osmo\_use\_count\_by}}
\index{osmo\_use\_count\_by@{osmo\_use\_count\_by}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_by()}
{\footnotesize\ttfamily int32\+\_\+t osmo\+\_\+use\+\_\+count\+\_\+by (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc,  }\item[{const char $\ast$}]{use }\end{DoxyParamCaption})}



Return use count by a single use token. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em uc} & Use counts to look up in. \\
\hline
\mbox{\texttt{ in}}  & {\em use} & Use token. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Use count, or 0 if uc is NULL or use token is not present. 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::count}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+find()}, and \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use}.

\mbox{\label{group__use__count_ga90705ba109a7da55760fba37c5821817}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_create@{osmo\_use\_count\_create}}
\index{osmo\_use\_count\_create@{osmo\_use\_count\_create}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_create()}
{\footnotesize\ttfamily static struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$ osmo\+\_\+use\+\_\+count\+\_\+create (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc,  }\item[{const char $\ast$}]{use }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [static]}}



Allocate a new use count entry, happens implicitly in \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}. 



References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, \textbf{ INIT\+\_\+\+LLIST\+\_\+\+HEAD}, \textbf{ llist\+\_\+add\+\_\+tail()}, \textbf{ llist\+\_\+head\+::next}, \textbf{ osmo\+\_\+use\+\_\+count\+::talloc\+\_\+object}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use\+\_\+count}, and \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+counts}.



Referenced by \textbf{ \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}.

\mbox{\label{group__use__count_ga0dcc3abaab263ca652b99214f2396298}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_find@{osmo\_use\_count\_find}}
\index{osmo\_use\_count\_find@{osmo\_use\_count\_find}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_find()}
{\footnotesize\ttfamily struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$ osmo\+\_\+use\+\_\+count\+\_\+find (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc,  }\item[{const char $\ast$}]{use }\end{DoxyParamCaption})}



References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry}, \textbf{ llist\+\_\+head\+::next}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use}, and \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+counts}.



Referenced by \textbf{ \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}, and \textbf{ osmo\+\_\+use\+\_\+count\+\_\+by()}.

\mbox{\label{group__use__count_ga7d4005ec0820c11ef960ea966b6baff9}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_free@{osmo\_use\_count\_free}}
\index{osmo\_use\_count\_free@{osmo\_use\_count\_free}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_free()}
{\footnotesize\ttfamily void osmo\+\_\+use\+\_\+count\+\_\+free (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$}]{use\+\_\+count\+\_\+entry }\end{DoxyParamCaption})}



Deallocate a use count entry. 

Normally, this is not necessary -- it is ok and even desirable to leave use count entries around even when they reach a count of zero, until the use\+\_\+count-\/$>$talloc\+\_\+object deallocates and removes all of them in one flush. This avoids repeated allocation and deallocation for use tokens, because use count entries that have reached zero count are repurposed for any other use tokens. A cleanup makes sense only if a very large number of differing use tokens surged at the same time, and the owning object will not be deallocated soon; if so, this should be done by the osmo\+\_\+use\+\_\+count\+\_\+cb\+\_\+t implementation.

\doxyref{osmo\+\_\+use\+\_\+count\+\_\+free()}{p.}{group__use__count_ga7d4005ec0820c11ef960ea966b6baff9} must {\itshape not} be called on use count entries that were added by \doxyref{osmo\+\_\+use\+\_\+count\+\_\+make\+\_\+static\+\_\+entries()}{p.}{group__use__count_ga1d3601b4f5093407d57ca3f5e1c093cc}. This is the responsibility of the \doxyref{osmo\+\_\+use\+\_\+count\+\_\+cb\+\_\+t()}{p.}{group__use__count_ga4497d9dc69e733d16d33a455d385931e} implementation.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em use\+\_\+count\+\_\+entry} & Use count entry to unlist and free. \\
\hline
\end{DoxyParams}


References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, and \textbf{ llist\+\_\+del()}.

\mbox{\label{group__use__count_ga1d3601b4f5093407d57ca3f5e1c093cc}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_make\_static\_entries@{osmo\_use\_count\_make\_static\_entries}}
\index{osmo\_use\_count\_make\_static\_entries@{osmo\_use\_count\_make\_static\_entries}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_make\_static\_entries()}
{\footnotesize\ttfamily void osmo\+\_\+use\+\_\+count\+\_\+make\+\_\+static\+\_\+entries (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc,  }\item[{struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$}]{buf,  }\item[{size\+\_\+t}]{buf\+\_\+n\+\_\+entries }\end{DoxyParamCaption})}



Add N static use token entries to avoid dynamic allocation of use count tokens. 

When not using this function, use count entries are talloc allocated from uc-\/$>$talloc\+\_\+object as talloc context. This means that there are small dynamic allocations for each use count token. \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233} normally leaves zero-\/count entries around and re-\/purposes them later, so the number of small allocations is at most the number of concurrent differently-\/named uses of the same object. If that is not enough, this function allows completely avoiding dynamic use count allocations, by adding N static entries with a zero count and a NULL use token. They will be used by \doxyref{osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}{p.}{group__use__count_ga3457c05c5d2b707d99eb01704dc5f233}, and, if the caller avoids using \doxyref{osmo\+\_\+use\+\_\+count\+\_\+free()}{p.}{group__use__count_ga7d4005ec0820c11ef960ea966b6baff9}, the \doxyref{osmo\+\_\+use\+\_\+count}{p.}{structosmo__use__count} implementation never deallocates them. The idea is that the entries are members of the uc-\/$>$talloc\+\_\+object, or that they will by other means be implicitly deallocated by the talloc\+\_\+object. It is fine to call osmo\+\_\+use\+\_\+count\+\_\+make\+\_\+static\+\_\+entries(buf\+\_\+n\+\_\+entries=N) and later have more than N concurrent uses, i.\+e. it is no problem to mix static and dynamic entries. To completely avoid dynamic use count entries, N has to $>$= the maximum number of concurrent differently-\/named uses that will occur in the lifetime of the talloc\+\_\+object.

struct my\+\_\+object \{ struct \doxyref{osmo\+\_\+use\+\_\+count}{p.}{structosmo__use__count} use\+\_\+count; struct \doxyref{osmo\+\_\+use\+\_\+count\+\_\+entry}{p.}{structosmo__use__count__entry} use\+\_\+count\+\_\+buf[3]; // planning for 3 concurrent users \};

void example() \{ struct my\+\_\+object $\ast$o = talloc\+\_\+zero(ctx, struct my\+\_\+object); osmo\+\_\+use\+\_\+count\+\_\+make\+\_\+static\+\_\+entries(\&o-\/$>$use\+\_\+count, o-\/$>$use\+\_\+count\+\_\+buf, ARRAY\+\_\+\+SIZE(o-\/$>$use\+\_\+count\+\_\+buf)); \} 

References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, \textbf{ INIT\+\_\+\+LLIST\+\_\+\+HEAD}, \textbf{ llist\+\_\+add\+\_\+tail()}, \textbf{ llist\+\_\+head\+::next}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use\+\_\+count}, and \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+counts}.

\mbox{\label{group__use__count_ga7b49bfded7003847ba6bcf2e021cb4d9}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_name\_buf@{osmo\_use\_count\_name\_buf}}
\index{osmo\_use\_count\_name\_buf@{osmo\_use\_count\_name\_buf}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_name\_buf()}
{\footnotesize\ttfamily const char $\ast$ osmo\+\_\+use\+\_\+count\+\_\+name\+\_\+buf (\begin{DoxyParamCaption}\item[{char $\ast$}]{buf,  }\item[{size\+\_\+t}]{buf\+\_\+len,  }\item[{const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc }\end{DoxyParamCaption})}



Write a comprehensive listing of use counts to a string buffer. 

Reads like \char`\"{}12 (3$\ast$barring,fighting,8$\ast$kungfoo)\char`\"{}. 
\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in,out}}  & {\em buf} & Destination buffer. \\
\hline
\mbox{\texttt{ in}}  & {\em buf\+\_\+len} & sizeof(buf). \\
\hline
\mbox{\texttt{ in}}  & {\em uc} & Use counts to print. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
buf, always nul-\/terminated (except when buf\+\_\+len $<$ 1). 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+buf()}.

\mbox{\label{group__use__count_ga98cee57f336dcd019ccce57563e2b2ea}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_repurpose\_zero\_entry@{osmo\_use\_count\_repurpose\_zero\_entry}}
\index{osmo\_use\_count\_repurpose\_zero\_entry@{osmo\_use\_count\_repurpose\_zero\_entry}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_repurpose\_zero\_entry()}
{\footnotesize\ttfamily static struct \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry} $\ast$ osmo\+\_\+use\+\_\+count\+\_\+repurpose\+\_\+zero\+\_\+entry (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc,  }\item[{const char $\ast$}]{use }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [static]}}



Find a use count entry that currently has zero count, and re-\/use that for this new use token. 



References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::count}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry}, \textbf{ llist\+\_\+head\+::next}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use}, and \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+counts}.



Referenced by \textbf{ \+\_\+osmo\+\_\+use\+\_\+count\+\_\+get\+\_\+put()}.

\mbox{\label{group__use__count_ga0a979c7c3979e7cbb0981172c426a00f}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_to\_str\_buf@{osmo\_use\_count\_to\_str\_buf}}
\index{osmo\_use\_count\_to\_str\_buf@{osmo\_use\_count\_to\_str\_buf}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_to\_str\_buf()}
{\footnotesize\ttfamily int osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+buf (\begin{DoxyParamCaption}\item[{char $\ast$}]{buf,  }\item[{size\+\_\+t}]{buf\+\_\+len,  }\item[{const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc }\end{DoxyParamCaption})}



Write a comprehensive listing of use counts to a string buffer. 

Reads like \char`\"{}12 (3$\ast$barring,fighting,8$\ast$kungfoo)\char`\"{}. 
\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in,out}}  & {\em buf} & Destination buffer. \\
\hline
\mbox{\texttt{ in}}  & {\em buf\+\_\+len} & sizeof(buf). \\
\hline
\mbox{\texttt{ in}}  & {\em uc} & Use counts to print. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes that would be written, like snprintf(). 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+strbuf\+::buf}, \textbf{ osmo\+\_\+strbuf\+::chars\+\_\+needed}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::count}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry}, \textbf{ llist\+\_\+head\+::next}, \textbf{ OSMO\+\_\+\+STRBUF\+\_\+\+PRINTF}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+total()}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::use}, and \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+counts}.



Referenced by \textbf{ osmo\+\_\+use\+\_\+count\+\_\+name\+\_\+buf()}, and \textbf{ osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+c()}.

\mbox{\label{group__use__count_gac2e6c82a4809bae02212a09ce1e22a21}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_to\_str\_c@{osmo\_use\_count\_to\_str\_c}}
\index{osmo\_use\_count\_to\_str\_c@{osmo\_use\_count\_to\_str\_c}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_to\_str\_c()}
{\footnotesize\ttfamily char $\ast$ osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+c (\begin{DoxyParamCaption}\item[{void $\ast$}]{ctx,  }\item[{const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc }\end{DoxyParamCaption})}



Write a comprehensive listing of use counts to a talloc allocated string buffer. 

Reads like \char`\"{}12 (3$\ast$barring,fighting,8$\ast$kungfoo)\char`\"{}. 
\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em ctx} & talloc pool to allocate from. \\
\hline
\mbox{\texttt{ in}}  & {\em uc} & Use counts to print. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
buf, always nul-\/terminated. 
\end{DoxyReturn}


References \textbf{ OSMO\+\_\+\+NAME\+\_\+\+C\+\_\+\+IMPL}, and \textbf{ osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+buf()}.

\mbox{\label{group__use__count_ga34703c11c4da78bebd3322635b57e698}} 
\index{Use Counter@{Use Counter}!osmo\_use\_count\_total@{osmo\_use\_count\_total}}
\index{osmo\_use\_count\_total@{osmo\_use\_count\_total}!Use Counter@{Use Counter}}
\doxysubsubsection{osmo\_use\_count\_total()}
{\footnotesize\ttfamily int32\+\_\+t osmo\+\_\+use\+\_\+count\+\_\+total (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+use\+\_\+count} $\ast$}]{uc }\end{DoxyParamCaption})}



Return the sum of all use counts, min-\/ and max-\/clamped at INT32\+\_\+\+MIN and INT32\+\_\+\+MAX. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em uc} & Use counts to sum up. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Accumulated counts, or 0 if uc is NULL. 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::count}, \textbf{ count\+\_\+safe()}, \textbf{ osmo\+\_\+use\+\_\+count\+\_\+entry\+::entry}, \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry}, \textbf{ llist\+\_\+head\+::next}, and \textbf{ osmo\+\_\+use\+\_\+count\+::use\+\_\+counts}.



Referenced by \textbf{ osmo\+\_\+use\+\_\+count\+\_\+to\+\_\+str\+\_\+buf()}.

