cgen – C-Generation Reference Documentation

cgen.dtype_to_ctype(dtype)

class cgen.Generable

Bases: ABC

__str__() → str

Return a single string (possibly containing newlines) representing this code construct.

abstract generate(with_semicolon: bool = True) → Generator[str]

Generate (i.e. yield) the lines making up this code construct.

class cgen.Block(contents=None)

Bases: Generable

class cgen.Collection(contents=None)

Bases: Block

cgen.Module

alias of Collection

class cgen.Line(text='')

Bases: Generable

Data and Functions

class cgen.FunctionBody(fdecl, body)

Bases: Generable

class cgen.Initializer(vdecl, data)

Bases: Generable

Preprocessor Code

class cgen.Define(symbol, value)

Bases: Generable

class cgen.Comment(text, skip_space=False)

Bases: Generable

class cgen.Include(filename, system=True)

Bases: Generable

class cgen.Pragma(value)

Bases: Generable

Declarators

class cgen.Declarator

Bases: Generable, ABC

generate(with_semicolon: bool = True) → Generator[str]

Generate (i.e. yield) the lines making up this code construct.

abstract get_decl_pair() → tuple[Sequence[str], str]

Return a tuple (type_lines, rhs).

type_lines is a non-empty list of lines (most often just a single one) describing the type of this declarator. rhs is the right- hand side that actually contains the function/array/constness notation making up the bulk of the declarator syntax.

inline(with_semicolon: bool = True) → str

Return the declarator as a single line.

class cgen.Value(typename: str, name: str)

Bases: Declarator

A simple declarator: typename and name are given as strings.

class cgen.POD(dtype: dtype, name: str)

Bases: Declarator

A simple declarator: The type is given as a numpy.dtype and the name is given as a string.

class cgen.Struct(tpname, fields, declname=None, pad_bytes=0)

Bases: Declarator

A structure declarator.

class cgen.GenerableStruct(tpname, fields, declname=None, align_bytes=None, aligned_prime_to=None)

Bases: Struct

__init__(tpname, fields, declname=None, align_bytes=None, aligned_prime_to=None)

Initialize a structure declarator. tpname is the name of the structure, while declname is the name used for the declarator. pad_bytes is the number of padding bytes added at the end of the structure. fields is a list of Declarator instances.

align_bytes is an integer that causes the structure to be padded to an integer multiple of itself. aligned_prime_to is a list of integers. If the resulting structure’s size is s, then s//align_bytes will be made prime to all numbers in aligned_prime_to. (Sounds obscure? It’s needed for avoiding bank conflicts in CUDA programming.)

__len__()

Return the number of bytes occupied by this struct.

make(**kwargs)

Build a binary, packed representation of self in a str instance with members set to the values specified in kwargs.

make_with_defaults(**kwargs)

Build a binary, packed representation of self in a str instance with members set to the values specified in kwargs.

Unlike make(), not all members have to occur in kwargs.

struct_format()

Return the format of the struct as digested by the struct module.

class cgen.Enum

Bases: Generable

An enum-like class for Python that can generate an equivalent C-level declaration. Does not work within the usual “declarator” framework because it uses macros to define values, and a separate typedef to define the value type.

Added in version 2013.2.

To use, derive from this class, and define the following things:

c_name

dtype

c_value_prefix

A (usually upper-case) prefix to be used as a prefix to the names defined on the Python side.

VALUE

Any class attribute with an all-upper-case name is taken to be as an enum value.

classmethod get_c_defines()

Return a string with C defines corresponding to these constants.

classmethod stringify_value(val)

Return a string description of the flags set in val.

Nested Declarators

class cgen.NestedDeclarator(subdecl: Declarator)

Bases: Declarator

class cgen.ArrayOf(subdecl: Declarator, count=None)

Bases: NestedDeclarator

class cgen.Const(subdecl: Declarator)

Bases: NestedDeclarator

class cgen.FunctionDeclaration(subdecl: Declarator, arg_decls: Sequence[Declarator])

Bases: NestedDeclarator

class cgen.MaybeUnused(subdecl: Declarator)

Bases: NestedDeclarator

class cgen.Pointer(subdecl)

Bases: NestedDeclarator

class cgen.Reference(subdecl)

Bases: Pointer

class cgen.Template(template_spec, subdecl)

Bases: NestedDeclarator

class cgen.AlignedAttribute(align_bytes, subdecl)

Bases: NestedDeclarator

Assigns an alignment for a definition of a type or an array.

class cgen.AlignValueAttribute(align_bytes, subdecl)

Bases: NestedDeclarator

Assigns an alignment for value of a pointer.

This is used for pointers where the user guarantees to the compiler that the value of the pointer has the alignment stated. AlignedAttribute on the other hand tells the compiler to declare the type or the array with the given alignment and cannot be used for telling the compiler that an existing pointer has a certain alignment guarantee. This attribute is currently supported by clang [1] and Intel [2] and is ignored by gcc.

[1]: https://reviews.llvm.org/D4635 [2]: https://www.intel.com/content/www/us/en/develop/documentation/oneapi-dpcpp-cpp-compiler-dev-guide-and-reference/top/compiler-reference/attributes/align-value.html

Declaration Specifiers

class cgen.DeclSpecifier(subdecl: Declarator, spec, sep=' ')

Bases: NestedDeclarator

class cgen.Static(subdecl)

Bases: DeclSpecifier

class cgen.Typedef(subdecl)

Bases: DeclSpecifier

Statements

class cgen.Statement(text: str)

Bases: Generable

class cgen.Assign(lvalue, rvalue)

Bases: Generable

class cgen.If(condition, then_, else_=None)

Bases: Generable

cgen.make_multiple_ifs(conditions_and_blocks, base=None)

class cgen.Loop(body)

Bases: Generable

class cgen.DoWhile(condition, body)

Bases: Loop

class cgen.For(start, condition, update, body)

Bases: Loop

class cgen.While(condition, body)

Bases: Loop

cgen.cuda – Extensions to generate CUDA-compatible C Sources

This module adds a few Nvidia CUDA features to cgen’s repertoire. This makes cgen a perfect complement to PyCuda: cgen generates the code, PyCuda compiles it, uploads it to the GPU and executes it.

The PyCuda manual has a tutorial on using the two together.

class cgen.cuda.CudaGlobal(subdecl)

Bases: DeclSpecifier

class cgen.cuda.CudaDevice(subdecl)

Bases: DeclSpecifier

class cgen.cuda.CudaShared(subdecl)

Bases: DeclSpecifier

class cgen.cuda.CudaConstant(subdecl)

Bases: DeclSpecifier

cgen.opencl – Extensions to generate OpenCL-compatible C Sources

cgen.opencl.dtype_to_cltype(dtype)

Kernels and Kernel Arguments

class cgen.opencl.CLKernel(subdecl)

Bases: DeclSpecifier

class cgen.opencl.CLConstant(subdecl)

Bases: DeclSpecifier

class cgen.opencl.CLLocal(subdecl)

Bases: DeclSpecifier

class cgen.opencl.CLGlobal(subdecl)

Bases: DeclSpecifier

class cgen.opencl.CLImage(dims, mode, name)

Bases: Value

Function Attributes

class cgen.opencl.CLVecTypeHint(subdecl, dtype=None, count=None, type_str=None)

Bases: NestedDeclarator

class cgen.opencl.CLWorkGroupSizeHint(dim, subdecl)

See Sec 6.7.2 of OpenCL 2.0 spec, Version V2.2-11.

class cgen.opencl.CLRequiredWorkGroupSize(dim, subdecl)

See Sec 6.7.2 of OpenCL 2.0 spec, Version V2.2-11.

Vector PODs

class cgen.opencl.CLVectorPOD(dtype, count, name)

Bases: Declarator