\hypertarget{group__Eina__Binshare__Group}{\section{Binary Share}
\label{group__Eina__Binshare__Group}\index{Binary Share@{Binary Share}}
}


This group discusses the functions that allow you to store one copy of an object, and use it throughout your program.  


\subsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \hyperlink{group__Eina__Binshare__Group_ga1472e150f4fbaa3f05e5c583b1698b40}{eina\+\_\+binshare\+\_\+add}(ptr)~\hyperlink{group__Eina__Binshare__Group_ga376ff9324527657d65627d9630c5da07}{eina\+\_\+binshare\+\_\+add\+\_\+length}(ptr, sizeof($\ast$ptr))
\begin{DoxyCompactList}\small\item\em Retrieves an instance of a blob for use in a program. \end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
\hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{E\+A\+P\+I} const void $\ast$ \hyperlink{group__Eina__Binshare__Group_ga376ff9324527657d65627d9630c5da07}{eina\+\_\+binshare\+\_\+add\+\_\+length} (const void $\ast$obj, unsigned int olen) \hyperlink{group__Eina__Types__Group_ga4ba89e4b58eff707a6cf05ffe0cd4dea}{E\+I\+N\+A\+\_\+\+W\+A\+R\+N\+\_\+\+U\+N\+U\+S\+E\+D\+\_\+\+R\+E\+S\+U\+L\+T}
\begin{DoxyCompactList}\small\item\em Retrieves an instance of an object for use in a program. \end{DoxyCompactList}\item 
\hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{E\+A\+P\+I} const void $\ast$ \hyperlink{group__Eina__Binshare__Group_ga7637cf798dfdf90ce7d0bed8738e8c33}{eina\+\_\+binshare\+\_\+ref} (const void $\ast$obj)
\begin{DoxyCompactList}\small\item\em Increments references of the given shared object. \end{DoxyCompactList}\item 
\hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{E\+A\+P\+I} void \hyperlink{group__Eina__Binshare__Group_gac4083405412aa0713805fea3444fbaa3}{eina\+\_\+binshare\+\_\+del} (const void $\ast$obj)
\begin{DoxyCompactList}\small\item\em Notes that the given object has lost an instance. \end{DoxyCompactList}\item 
\hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{E\+A\+P\+I} int \hyperlink{group__Eina__Binshare__Group_ga2fe833551e802405367099585f44cd76}{eina\+\_\+binshare\+\_\+length} (const void $\ast$obj) \hyperlink{group__Eina__Types__Group_ga4ba89e4b58eff707a6cf05ffe0cd4dea}{E\+I\+N\+A\+\_\+\+W\+A\+R\+N\+\_\+\+U\+N\+U\+S\+E\+D\+\_\+\+R\+E\+S\+U\+L\+T} \hyperlink{group__Eina__Types__Group_ga4669a55a23089d0f9b70702ef05cea68}{E\+I\+N\+A\+\_\+\+P\+U\+R\+E}
\begin{DoxyCompactList}\small\item\em Notes that the given object {\bfseries must} be shared. \end{DoxyCompactList}\item 
\hyperlink{group__Eina__Types__Group_ga3db3556eec8ef18cb8ddb43816974ac8}{E\+A\+P\+I} void \hyperlink{group__Eina__Binshare__Group_gafd5871a8191c3afd846480144d8287dd}{eina\+\_\+binshare\+\_\+dump} (void)
\begin{DoxyCompactList}\small\item\em Dumps the contents of share\+\_\+common. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
This group discusses the functions that allow you to store one copy of an object, and use it throughout your program. 

This is a method to reduce the number of duplicated objects kept in the memory.

For more information, you can look at the \hyperlink{tutorial_binshare_page}{Binary Share Tutorial}. 

\subsection{Macro Definition Documentation}
\hypertarget{group__Eina__Binshare__Group_ga1472e150f4fbaa3f05e5c583b1698b40}{\index{Binary Share@{Binary Share}!eina\+\_\+binshare\+\_\+add@{eina\+\_\+binshare\+\_\+add}}
\index{eina\+\_\+binshare\+\_\+add@{eina\+\_\+binshare\+\_\+add}!Binary Share@{Binary Share}}
\subsubsection[{eina\+\_\+binshare\+\_\+add}]{\setlength{\rightskip}{0pt plus 5cm}\#define eina\+\_\+binshare\+\_\+add(
\begin{DoxyParamCaption}
\item[{}]{ptr}
\end{DoxyParamCaption}
)~{\bf eina\+\_\+binshare\+\_\+add\+\_\+length}(ptr, sizeof($\ast$ptr))}}\label{group__Eina__Binshare__Group_ga1472e150f4fbaa3f05e5c583b1698b40}


Retrieves an instance of a blob for use in a program. 


\begin{DoxyParams}{Parameters}
{\em ptr} & The binary blob to retrieve an instance of \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the string on success, otherwise {\ttfamily N\+U\+L\+L} on failure
\end{DoxyReturn}
This macro retrieves an instance of {\ttfamily obj}. If {\ttfamily obj} is {\ttfamily N\+U\+L\+L}, then {\ttfamily N\+U\+L\+L} is returned. If {\ttfamily obj} is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the blobs to be searched and a duplicated blob of {\ttfamily obj} is returned.

\begin{DoxyNote}{Note}
This macro essentially calls eina\+\_\+binshare\+\_\+add\+\_\+length with ptr and sizeof($\ast$ptr) as the parameters. It's useful for pointers to structures.
\end{DoxyNote}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__Eina__Stringshare__Group_ga7102630f25d779cd216e48f1369f65b1}{eina\+\_\+stringshare\+\_\+add\+\_\+length()} 
\end{DoxySeeAlso}


\subsection{Function Documentation}
\hypertarget{group__Eina__Binshare__Group_ga376ff9324527657d65627d9630c5da07}{\index{Binary Share@{Binary Share}!eina\+\_\+binshare\+\_\+add\+\_\+length@{eina\+\_\+binshare\+\_\+add\+\_\+length}}
\index{eina\+\_\+binshare\+\_\+add\+\_\+length@{eina\+\_\+binshare\+\_\+add\+\_\+length}!Binary Share@{Binary Share}}
\subsubsection[{eina\+\_\+binshare\+\_\+add\+\_\+length}]{\setlength{\rightskip}{0pt plus 5cm}{\bf E\+A\+P\+I} const void$\ast$ eina\+\_\+binshare\+\_\+add\+\_\+length (
\begin{DoxyParamCaption}
\item[{const void $\ast$}]{obj, }
\item[{unsigned int}]{olen}
\end{DoxyParamCaption}
)}}\label{group__Eina__Binshare__Group_ga376ff9324527657d65627d9630c5da07}


Retrieves an instance of an object for use in a program. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\tt in}  & {\em obj} & The binary object to retrieve an instance of \\
\hline
\mbox{\tt in}  & {\em olen} & The byte size \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the object on success, otherwise {\ttfamily N\+U\+L\+L} on failure
\end{DoxyReturn}
This function retrieves an instance of {\ttfamily obj}. If {\ttfamily obj} is {\ttfamily N\+U\+L\+L}, then {\ttfamily N\+U\+L\+L} is returned. If {\ttfamily obj} is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the objects to be searched and a duplicated object of {\ttfamily obj} is returned.

\begin{DoxyNote}{Note}
This function does not check the object size, but uses the exact given size. This can be used to share a part of a larger object or subobject.
\end{DoxyNote}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__Eina__Binshare__Group_ga1472e150f4fbaa3f05e5c583b1698b40}{eina\+\_\+binshare\+\_\+add()} 
\end{DoxySeeAlso}
\hypertarget{group__Eina__Binshare__Group_ga7637cf798dfdf90ce7d0bed8738e8c33}{\index{Binary Share@{Binary Share}!eina\+\_\+binshare\+\_\+ref@{eina\+\_\+binshare\+\_\+ref}}
\index{eina\+\_\+binshare\+\_\+ref@{eina\+\_\+binshare\+\_\+ref}!Binary Share@{Binary Share}}
\subsubsection[{eina\+\_\+binshare\+\_\+ref}]{\setlength{\rightskip}{0pt plus 5cm}{\bf E\+A\+P\+I} const void$\ast$ eina\+\_\+binshare\+\_\+ref (
\begin{DoxyParamCaption}
\item[{const void $\ast$}]{obj}
\end{DoxyParamCaption}
)}}\label{group__Eina__Binshare__Group_ga7637cf798dfdf90ce7d0bed8738e8c33}


Increments references of the given shared object. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\tt in}  & {\em obj} & The shared object \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the object on success, otherwise {\ttfamily N\+U\+L\+L} on failure
\end{DoxyReturn}
\begin{DoxyNote}{Note}
This is similar to eina\+\_\+share\+\_\+common\+\_\+add(), but it's faster since it avoids lookups if possible, but on the down side it requires the parameter to be shared before, in other words, it must be the return of a previous \hyperlink{group__Eina__Binshare__Group_ga1472e150f4fbaa3f05e5c583b1698b40}{eina\+\_\+binshare\+\_\+add()}.

There is no unref since this is the work of \hyperlink{group__Eina__Binshare__Group_gac4083405412aa0713805fea3444fbaa3}{eina\+\_\+binshare\+\_\+del()}. 
\end{DoxyNote}
\hypertarget{group__Eina__Binshare__Group_gac4083405412aa0713805fea3444fbaa3}{\index{Binary Share@{Binary Share}!eina\+\_\+binshare\+\_\+del@{eina\+\_\+binshare\+\_\+del}}
\index{eina\+\_\+binshare\+\_\+del@{eina\+\_\+binshare\+\_\+del}!Binary Share@{Binary Share}}
\subsubsection[{eina\+\_\+binshare\+\_\+del}]{\setlength{\rightskip}{0pt plus 5cm}{\bf E\+A\+P\+I} void eina\+\_\+binshare\+\_\+del (
\begin{DoxyParamCaption}
\item[{const void $\ast$}]{obj}
\end{DoxyParamCaption}
)}}\label{group__Eina__Binshare__Group_gac4083405412aa0713805fea3444fbaa3}


Notes that the given object has lost an instance. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\tt in}  & {\em obj} & The given object\\
\hline
\end{DoxyParams}
This function decreases the reference counter associated to {\ttfamily obj} if it exists. If that counter reaches {\ttfamily 0}, the memory associated to {\ttfamily obj} is freed. If {\ttfamily obj} is {\ttfamily N\+U\+L\+L}, the function returns immediately.

\begin{DoxyWarning}{Warning}
If the given pointer is not shared, bad things happen, mostly a segmentation fault. 
\end{DoxyWarning}
\hypertarget{group__Eina__Binshare__Group_ga2fe833551e802405367099585f44cd76}{\index{Binary Share@{Binary Share}!eina\+\_\+binshare\+\_\+length@{eina\+\_\+binshare\+\_\+length}}
\index{eina\+\_\+binshare\+\_\+length@{eina\+\_\+binshare\+\_\+length}!Binary Share@{Binary Share}}
\subsubsection[{eina\+\_\+binshare\+\_\+length}]{\setlength{\rightskip}{0pt plus 5cm}{\bf E\+A\+P\+I} int eina\+\_\+binshare\+\_\+length (
\begin{DoxyParamCaption}
\item[{const void $\ast$}]{obj}
\end{DoxyParamCaption}
)}}\label{group__Eina__Binshare__Group_ga2fe833551e802405367099585f44cd76}


Notes that the given object {\bfseries must} be shared. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\tt in}  & {\em obj} & The shared object to know the length ~\newline
 It is safe to give {\ttfamily N\+U\+L\+L}, in which case {\ttfamily -\/1} is returned \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The length of the shared object
\end{DoxyReturn}
This function is a cheap way to know the length of a shared object.

\begin{DoxyWarning}{Warning}
If the given pointer is not shared, bad things happen, mostly a segmentation fault. If in doubt, try strlen(). 
\end{DoxyWarning}
\hypertarget{group__Eina__Binshare__Group_gafd5871a8191c3afd846480144d8287dd}{\index{Binary Share@{Binary Share}!eina\+\_\+binshare\+\_\+dump@{eina\+\_\+binshare\+\_\+dump}}
\index{eina\+\_\+binshare\+\_\+dump@{eina\+\_\+binshare\+\_\+dump}!Binary Share@{Binary Share}}
\subsubsection[{eina\+\_\+binshare\+\_\+dump}]{\setlength{\rightskip}{0pt plus 5cm}{\bf E\+A\+P\+I} void eina\+\_\+binshare\+\_\+dump (
\begin{DoxyParamCaption}
\item[{void}]{}
\end{DoxyParamCaption}
)}}\label{group__Eina__Binshare__Group_gafd5871a8191c3afd846480144d8287dd}


Dumps the contents of share\+\_\+common. 

This function dumps all the objects from share\+\_\+common to stdout with a D\+D\+D\+: prefix per line and a memory usage summary. 