src/c-types-{impl,parse}.lisp: Support C11 `_Atomic'.

[sod] / doc / clang.tex

diff --git a/doc/clang.tex b/doc/clang.tex
index 700033f..348c5b6 100644 (file)
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -46,6 +46,7 @@ The class hierarchy is shown in~\xref{fig:codegen.c-types.classes}.
           @|c-struct-type| \\
           @|c-union-type| \\
           @|c-enum-type| \- \\
+        @|c-atomic-type| \\
         @|c-pointer-type| \- \\
       @|c-array-type| \\
       @|c-function-type|
@@ -306,6 +307,29 @@ argument lists for methods.  This is done by @|c-type-equal-p|.
 \subsection{Type qualifiers and qualifiable types}
 \label{sec:clang.ctypes.qual}
 
+Qualifiers -- @|const|, @|volatile|, and so on -- are represented as lists of
+keywords attached to types.  Not all C types can carry qualifiers: notably,
+function and array types cannot be qualified.
+
+For the most part, the C qualifier keywords correspond to like-named Lisp
+keywords, only the Lisp keyword names are in uppercase.  The correspondence
+is shown in \xref{tab:clang.ctypes.qual}.
+
+\begin{table}
+  \begin{tabular}[C]{*2{>{\codeface}l}l}                           \hlx*{hv}
+    \thd{\textbf{C name}}       & \thd{\textbf{Lisp name}}      \\ \hlx{vhv}
+    _Atomic                     & :atomic                       \\
+    const                       & :const                        \\
+    restrict                    & :restrict                     \\
+    volatile                    & :volatile                     \\ \hlx*{vh}
+  \end{tabular}
+  \caption{C and Lisp qualifier names} \label{tab:clang.ctypes.qual}
+\end{table}
+
+The default behaviour, on output, is to convert keywords to lowercase and
+hope for the best: special cases can be dealt with by adding appropriate
+methods to \descref{c-qualifier-keyword}{gf}.
+
 \begin{describe}{cls}{qualifiable-c-type (c-type) \&key :qualifiers}
   The class @|qualifiable-c-type| describes C types which can bear
   `qualifiers' (\Cplusplus\ calls them `cv-qualifiers'): @|const|,
@@ -559,6 +583,38 @@ protocol.
 \end{describe}
 
 
+\subsection{Atomic types} \label{sec:clang.c-types.atomic}
+
+Atomic types are compound types.  The subtype of an atomic type is simply the
+underlying type of the object.  Note that, as far as Sod is concerned, atomic
+types are not the same as atomic-qualified types: you must be consistent
+about which you use.
+
+\begin{describe}{cls}
+    {c-atomic-type (qualifiable-c-type) \&key :qualifiers :subtype}
+  Represents an atomic type.  An instance denotes the C type
+  @|_Atomic(@<subtype>)|.
+
+  The @<subtype> may be any C type.\footnote{%
+    C does not permit atomic function or array types.} %
+  Two atomic types are equal if and only if their subtypes are equal and they
+  have matching qualifiers.  It is possible, though probably not useful, to
+  have an atomic-qualified atomic type.
+
+  The type specifier @|(atomic @<type-spec> @<qualifier>^*)| returns a type
+  qualified atomic @<subtype>, where @<subtype> is the type specified by
+  @<type-spec> and the @<qualifier>s are qualifier keywords (which are
+  evaluated).
+\end{describe}
+
+\begin{describe}{fun}
+    {make-atomic-type @<c-type> \&optional @<qualifiers> @> @<c-atomic-type>}
+  Return an object describing the type qualified atomic @<subtype>.  If
+  @<subtype> is interned, then the returned atomic type object is interned
+  also.
+\end{describe}
+
+
 \subsection{Pointer types} \label{sec:clang.c-types.pointer}
 
 Pointers are compound types.  The subtype of a pointer type is the type it