OpenCL_helpers/documentation/name_conventions-russian.tex

\subsection{Соглашения по именам}
\label{subsec:nameconventions}

\index{соглашения по именам}%
Для описания соглашений будут использованы следующие подстановки:
\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|*|&--&последовательность символов любой длины;\\
\verbI{Action}&--&смысловое название действия, например, <<Sync>> для
синхронизации или <<Fill>> для заполнения;\\
\verbI{Tname}&--&\textbf{t}ype \textbf{name}, смысловое название типа данных, не
обязательно соответствует техническому названию структуры;\\
\verbI{BTA}&--&\textbf{b}ase \textbf{t}ype \textbf{a}cronym, сокращение для
базового типа данных, так в библиотеке уже задействованы акронимы:\\
&&
\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%
При написании использованы следующие соглашения по именам сущностей:
\nopagebreak\par
{\NmCnvDescript\verb|__*|\\* сущности библиотеки для внутреннего использования
начинаются с двух знаков подчёркивания <<\verb|__|>>~(underscore).  При штатном
использовании библиотеки обращение к таким сущностям не предполагается.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Макроопределения}}\nopagebreak\par
{\NmCnvDescript\verb|_GHM_*|\\* \textbf{g}pgpu \textbf{h}ost \textbf{m}acro,
инструкция препроцессора для компилятора программ CPU.\par}
{\NmCnvDescript\verb|_GDM_*|\\* \textbf{g}pgpu \textbf{d}evice \textbf{m}acro,
инструкция препроцессора только для компилятора программ OpenCL.\par}
{\NmCnvDescript\verb|_GHDM_*|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{m}acro, инструкция препроцессора единая для компиляторов CPU и OpenCL.
\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Типы}}\nopagebreak\par
{\NmCnvDescript\verb|_GHT_*|\\* \textbf{g}pgpu \textbf{h}ost \textbf{t}ype, тип
данных для программ CPU.\par}
{\NmCnvDescript\verb|_GDT_*|\\* \textbf{g}pgpu \textbf{d}evice \textbf{t}ype,
тип данных для программ OpenCL.\par}
{\NmCnvDescript\verb|_GHDT_*|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{t}ype, тип данных единый для программ CPU и OpenCL.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Перечисления}}\nopagebreak\par
{\NmCnvDescript\verb|_GHE_*|\\* \textbf{g}pgpu \textbf{h}ost
\textbf{e}numeration, перечисление для программ CPU.\par}
{\NmCnvDescript\verb|_GDE_*|\\* \textbf{g}pgpu \textbf{d}evice
\textbf{e}numeration, перечисление для программ OpenCL.\par}
{\NmCnvDescript\verb|_GHDE_*|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{e}numeration, перечисление единое для программ CPU и OpenCL.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Функции}}\nopagebreak\par
{\NmCnvDescript\verb|_ghf_*()|\\* \textbf{g}pgpu \textbf{h}ost
\textbf{f}unction, функция библиотеки доступная для использования только в
программах CPU.\par}
{\NmCnvDescript\verb|_gdf_*()|\\* \textbf{g}pgpu \textbf{d}evice
\textbf{f}unction, функция библиотеки доступная для использования только в
программах OpenCL.\par}
{\NmCnvDescript\verb|_ghdf_*()|\\* \textbf{g}pgpu \textbf{h}ost-\textbf{d}evice
\textbf{f}unction, функция единая для программ CPU и OpenCL.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript\verb|*_wdc*()|\\* \textbf{w}ith \textbf{d}ata \textbf{c}leaner,
особый тип функции. Если при выполнении такой функции возникнет ошибка, то будет
выполнена функция обратного вызова (callback), которая освобождает память и
обнуляет структуры из поля пользовательских данных рабочей конфигурации
(workset). Подробнее~см.~п.\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, функция возвращает структуру с полями (членами)
инициализированными значениями по умолчанию. При этом не производится выделение
памяти, а полям-указателям присваивается значение \verb|NULL|. Присвоение
значения возвращаемого такой функцией существующей структуре может привести к
утечке памяти, в связи с чем функции \verb|*_decl*()| вызываются только при
объявлении структуры.\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, функция выделяет память для всех
полей-указателей структуры \verbI{Tname}, указатель на которую получен из
аргументов. Затем заполняет поля структуры и выделенную память в соответствии со
своими аргументами. Аналог конструктора. При возникновении ошибки возвращает
значение \verb|int| отличное от ноля и полностью освобождает память создаваемой
структуры \verbI{Tname} включая поля-структуры. \verbI{Tname}~--~смысловое
название, которое может не соответствовать техническому обозначению структуры.
\par
\begin{ImpNote}
если функции \verb|*_genr*()| передан
указатель на существующую структуру, то структура будет корректно пересоздана с
удалением всех предыдущих данных и освобождением соответствующей памяти, включая
поля-структуры.
\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()|\\*
функция проводит минимальную проверку целостности данных структуры и возвращает
значение \verb|int|. Если данные структуры целостны, функция
\verb|*_is*_Valid()| вернёт 1, в ином случае будет возвращён 0.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript%
\verb|*|\verbI{ActionTname}\verb|()|\nopagebreak\par
\verb|*|\verbI{ActionTname}\verb|_|\verbI{BTA}\verb|()|\\*
функция производит действие \verbI{Action} с типом \verbI{Tname}. При
возникновении ошибки возвращает значение \verb|int| отличное от ноля и полностью
освобождает память структуры \verbI{Tname} включая поля-структуры.
\verbI{Tname}~--~смысловое название, которое может не соответствовать
техническому обозначению структуры.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript%
\verb|*_wipe|\verbI{Tname}\verb|()|\nopagebreak\par
\verb|*_wipe|\verbI{Tname}\verb|_|\verbI{BTA}\verb|()|\\*
функция полностью освобождает память, занимаемую полями структуры \verbI{Tname}
включая поля-структуры, присваивает всем полям структуры значения по умолчанию,
а полям-указателям значение \verb|NULL|. После применения функции
\verb|*_wipe*()| состояние структуры аналогично возвращённому функцией
\verb|*_decl*()| и память занимаемая структурой может быть освобождена или снова
применена функция \verb|*_genr*()|. \verbI{Tname}~--~смысловое название, которое
может не соответствовать техническому обозначению структуры.\par}
\end{samepage}
\bigskip

\begin{samepage}
{\NmCnvDescript\verb|*_get|\verbI{Tname}\Verb|()|\\* функция непрямого доступа к
данным, при вызове возвращает значение \verbI{Tname} полученное из аргументов
функции. \verbI{Tname}~--~смысловое название, которое может не соответствовать
техническому обозначению структуры.\par}
\end{samepage}
\bigskip

\begin{samepage}
\centerline{\textbf{Файлы}}\nopagebreak\par
{\NmCnvDescript\Verb|*.clc|\\* файл с исходным кодом OpenCL программы на языке
OpenCL C.\par}
{\NmCnvDescript\Verb|*.clh|\\* заголовочный файл (header) с исходным кодом
OpenCL заголовка на языке OpenCL C.\par}
{\NmCnvDescript\Verb|*.clo|\\* скомпилированный объект (object) OpenCL. Имеет
смысл только для OpenCL-устройств одной архитектуры.\par}
{\NmCnvDescript\Verb|*.clso|\\* скомпонованная библиотека (shared
object/library) OpenCL. Имеет смысл только для OpenCL-устройств одной
архитектуры.\par}
{\NmCnvDescript\Verb|*.clexe|\\* скомпонованный исполняемый файл (executable)
OpenCL. Имеет смысл только для OpenCL-устройств одной архитектуры.\par}
{\NmCnvDescript\Verb|*.clout|\\* файл OpenCL, содержание которого средствами
библиотеки установить не удалось.\par}
{\NmCnvDescript\verb|*.log|\\* файл-журнал.\par}
\end{samepage}