OpenCL_helpers/documentation/name_conventions-english.tex

\subsection{Naming conventions}
\label{subsec:nameconventions}

\index{naming conventions}%
The following substitutions were used to describe the conventions:
\nopagebreak\par\bigskip
{%
\setlength{\leftskip}{0pt}\setlength{\parindent}{-\tabcolsep}%
\SetLenVarWithWidth{\Acol}{\verbI{Action}}%
\SetLenVarWithWidth{\Bcol}{--}%
\begin{tabular}%
    {p{\Acol}p{\Bcol}p{\linewidth-\Acol-\Bcol-4\tabcolsep}}
\verb|*|&--&any string of characters;\\
\verbI{Action}&--&semantic name of an action, for example, <<Sync>> for
synchronization or <<Fill>> for filling;\\
\verbI{Tname}&--&\textbf{t}ype \textbf{name}, semantic name of an data type, it
does not obligingly corresponds to the technical name of the structure;\\
\verbI{BTA}&--&\textbf{b}ase \textbf{t}ype \textbf{a}cronym, acronym for a basic
data type, so the following acronyms were used in the library already:\\
&&
\begin{tabular}{lllllll}
&&&\verb|i8| &(\verb|signed char|),    &\verb|u8| &(\verb|unsigned char|),\\
&&&\verb|i16|&(\verb|signed short|),   &\verb|u16|&(\verb|unsigned short|),\\
&&&\verb|i32|&(\verb|signed int|),     &\verb|u32|&(\verb|unsigned int|),\\
&&&\verb|i64|&(\verb|signed long int|),&\verb|u64|&(\verb|unsigned long int|),\\
&&&\verb|f32|&(\verb|float|),          &\verb|f64|&(\verb|double|).
\end{tabular}
\end{tabular}
}
\bigskip

\begin{samepage}
\noindent%
The following naming conventions were used in the library:\nopagebreak\par
{\NmCnvDescript\verb|__*|\\* the library instances for internal use begin with two underscores. While regular use of the library, using of such instances is not assumed.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Macrodefinitions}}\nopagebreak\par
{\NmCnvDescript\verb|_GHM_*|\\* \textbf{g}pgpu \textbf{h}ost \textbf{m}acro,
preprocessor macrodefinition for the CPU program compiler.\par}
{\NmCnvDescript\verb|_GDM_*|\\* \textbf{g}pgpu \textbf{d}evice \textbf{m}acro,
preprocessor macrodefinition for the OpenCL program compiler.\par}
{\NmCnvDescript\verb|_GHDM_*|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{m}acro, preprocessor macrodefinition common for the CPU program compiler 
and the OpenCL program compiler.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Data types}}\nopagebreak\par
{\NmCnvDescript\verb|_GHT_*|\\* \textbf{g}pgpu \textbf{h}ost \textbf{t}ype, data type for CPU programs.\par}
{\NmCnvDescript\verb|_GDT_*|\\* \textbf{g}pgpu \textbf{d}evice \textbf{t}ype, data type for OpenCL programs.\par}
{\NmCnvDescript\verb|_GHDT_*|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{t}ype, data type common for CPU and OpenCL programs.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Enumerations}}\nopagebreak\par
{\NmCnvDescript\verb|_GHE_*|\\* \textbf{g}pgpu \textbf{h}ost
\textbf{e}numeration, enumeration for CPU programs.\par}
{\NmCnvDescript\verb|_GDE_*|\\* \textbf{g}pgpu \textbf{d}evice
\textbf{e}numeration, enumeration for OpenCL programs.\par}
{\NmCnvDescript\verb|_GHDE_*|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{e}numeration, enumeration common for CPU and OpenCL programs.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Functions}}\nopagebreak\par
{\NmCnvDescript\verb|_ghf_*()|\\* \textbf{g}pgpu \textbf{h}ost
\textbf{f}unction, library function available for CPU programs only.\par}
{\NmCnvDescript\verb|_gdf_*()|\\* \textbf{g}pgpu \textbf{d}evice
\textbf{f}unction, library function available for OpenCL programs only.\par}
{\NmCnvDescript\verb|_ghdf_*()|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{f}unction, library function common for CPU and OpenCL programs.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript\verb|*_wdc*()|\\* \textbf{w}ith \textbf{d}ata \textbf{c}leaner,
special type of function. If error occurred while the execution of such
function, then callback function would be called which deallocates memory and
sets to zeroes members of structure from the user data member of the workset,
for details see~s.\ref{subsec:workset}.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript%
\verb|*_decl|\verbI{Tname}\verb|()|\nopagebreak\par
\verb|*_decl|\verbI{Tname}\verb|_|\verbI{BTA}\verb|()|\\*
\textbf{decl}arator, function returns a structure with members initialized to
default values. The function does not allocate memory and \verbI{Tname}'s
members-pointers are set to \verb|NULL|. Assignment the value returned such a
function to an existing structure may lead to a memory leak, therefore
\verb|*_decl*()| functions are being called for structure declaration only.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript%
\verb|*_genr|\verbI{Tname}\verb|()|\nopagebreak\par
\verb|*_genr|\verbI{Tname}\verb|_|\verbI{BTA}\verb|()|\\*
\textbf{gen}e\textbf{r}ator, the function allocates memory for all
members-pointer of the \verbI{Tname} structure, the pointer to which is obtained
from the arguments. Then the function assign values in accordance with its
arguments. Such a function is analogue of the constructor. If an error occurred,
the function would return \verb|int| value other than zero and completely
deallocate memory of the \verbI{Tname} structure, including the
members-structures.
\verbI{Tname} is a semantic name, that does not obligingly corresponds to the
technical name of the structure.\par
\begin{ImpNote}
If a pointer to an existing structure was passed as an argument of the
\verb|*_genr*()| function, the structure would be correctly recreated with
the deletion of all previous data and the deallocation of the corresponding
memory, including the members-structures.
\end{ImpNote}
}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript%
\verb|*_is|\verbI{Tname}\verb|_Valid()|\nopagebreak\par
\verb|*_is|\verbI{Tname}\verb|_|\verbI{BTA}\verb|_Valid()|\\*
the function performs minimal integrity check of the structure data and returns
an \verb|int| value. If the structure data is integral, the \verb|*_is*_Valid()|
function returns 1, otherwise 0 is returned.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript%
\verb|*|\verbI{ActionTname}\verb|()|\nopagebreak\par
\verb|*|\verbI{ActionTname}\verb|_|\verbI{BTA}\verb|()|\\*
the function performs \verbI{Action} over a \verbI{Tname} type. If an error
occurred, an \verb|int| value other than zero would be returned and the memory
of the structure would be completely deallocated, including the
members-structures.
\verbI{Tname} is a semantic name, that does not obligingly corresponds to the
technical name of the structure.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript%
\verb|*_wipe|\verbI{Tname}\verb|()|\nopagebreak\par
\verb|*_wipe|\verbI{Tname}\verb|_|\verbI{BTA}\verb|()|\\*
the function completely deallocates the memory occupied by the members of the
\verbI{Tname} structure, including the members-structures, then assigns default
values to all of the structure members, and \verb|NULL| to the members-pointers.
After applying the \verb|*_wipe*()| function, the state of the \verbI{Tname}
structure is fully equivalent to the value returned by the \verb|*_decl*()|
function and the memory occupied by the structure can be deallocated or the
\verb|*_genr*()| function can be applied again. \verbI{Tname} is a semantic
name, that does not obligingly corresponds to the technical name of the
structure.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript\verb|*_get|\verbI{Tname}\Verb|()|\\* the indirect data access function, if is called returns the \verbI{Tname} value obtained from the function arguments. \verbI{Tname} is a semantic name, that does not obligingly
corresponds to the technical name of the structure.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Files}}\nopagebreak\par
{\NmCnvDescript\Verb|*.clc|\\* file with the source code of the OpenCL program in OpenCL C language.\par}
{\NmCnvDescript\Verb|*.clh|\\* header file with the source code of the OpenCL program in OpenCL C language.\par}
{\NmCnvDescript\Verb|*.clo|\\* compiled OpenCL object. It only makes sense for OpenCL devices of the same architecture.\par}
{\NmCnvDescript\Verb|*.clso|\\* linked OpenCL library (shared object/library). It only makes sense for OpenCL devices of the same architecture.\par}
{\NmCnvDescript\Verb|*.clexe|\\* linked OpenCL executable. It only makes sense for OpenCL devices of the same architecture.\par}
{\NmCnvDescript\Verb|*.clout|\\* an OpenCL file, content of which could not be identified using the library.\par}
{\NmCnvDescript\verb|*.log|\\* log file.\par}
\end{samepage}