Ceed

A Ceed is a library context representing control of a logical hardware resource.

Base library resources

typedef struct Ceed_private *Ceed

Typedefs and macros used in public interfaces and user QFunction source.

This line prevents IWYU from suggesting “ceed.h” Library context created by CeedInit()

typedef struct CeedRequest_private *CeedRequest

Non-blocking Ceed interfaces return a CeedRequest.

To perform an operation immediately, pass CEED_REQUEST_IMMEDIATE instead.

CeedRequest *const CEED_REQUEST_IMMEDIATE = &ceed_request_immediate

Request immediate completion.

This predefined constant is passed as the CeedRequest argument to interfaces when the caller wishes for the operation to be performed immediately. The code

CeedOperatorApply(op, ..., CEED_REQUEST_IMMEDIATE);

is semantically equivalent to

CeedRequest request;
CeedOperatorApply(op, ..., &request);
CeedRequestWait(&request);

See also

CEED_REQUEST_ORDERED

CeedRequest *const CEED_REQUEST_ORDERED = &ceed_request_ordered

Request ordered completion.

This predefined constant is passed as the CeedRequest argument to interfaces when the caller wishes for the operation to be completed in the order that it is submitted to the device. It is typically used in a construct such as:

CeedRequest request;
CeedOperatorApply(op1, ..., CEED_REQUEST_ORDERED);
CeedOperatorApply(op2, ..., &request);
// other optional work
CeedRequestWait(&request);

which allows the sequence to complete asynchronously but does not start op2 until op1 has completed.

Todo:: The current implementation is overly strict, offering equivalent semantics to CEED_REQUEST_IMMEDIATE.

See also

CEED_REQUEST_IMMEDIATE

int CeedRequestWait(CeedRequest *req)

Wait for a CeedRequest to complete.

Calling CeedRequestWait on a NULL request is a no-op.

User Functions

Parameters:

req – Address of CeedRequest to wait for; zeroed on completion.

Returns:

An error code: 0 - success, otherwise - failure

int CeedRegistryGetList(size_t *n, char ***const resources, CeedInt **priorities)

Get the list of available resource names for Ceed contexts.

Note: The caller is responsible for free()ing the resources and priorities arrays, but should not free() the contents of the resources array.

User Functions

Parameters:

n – [out] Number of available resources
resources – [out] List of available resource names
priorities – [out] Resource name prioritization values, lower is better

Returns:

An error code: 0 - success, otherwise - failure

int CeedInit(const char *resource, Ceed *ceed)

Initialize a Ceed: core components context to use the specified resource.

Note: Prefixing the resource with “help:” (e.g. “help:/cpu/self”) will result in CeedInt printing the current libCEED version number and a list of current available backend resources to stderr.

User Functions

See also

CeedRegister() CeedDestroy()

Parameters:

resource – [in] Resource to use, e.g., “/cpu/self”
ceed – [out] The library context

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetStream(Ceed ceed, void *handle)

Set the GPU stream for a Ceed context.

User Functions

Parameters:

ceed – [inout] Ceed context to set the stream
handle – [in] Handle to GPU stream

Returns:

An error code: 0 - success, otherwise - failure

int CeedReferenceCopy(Ceed ceed, Ceed *ceed_copy)

Copy the pointer to a Ceed context.

Both pointers should be destroyed with CeedDestroy().

Note: If the value of ceed_copy passed to this function is non-NULL, then it is assumed that ceed_copy is a pointer to a Ceed context. This Ceed context will be destroyed if ceed_copy is the only reference to this Ceed context.

User Functions

Parameters:

ceed – [in] Ceed context to copy reference to
ceed_copy – [inout] Variable to store copied reference

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetResource(Ceed ceed, const char **resource)

Get the full resource name for a Ceed context.

User Functions

Parameters:

ceed – [in] Ceed context to get resource name of
resource – [out] Variable to store resource name

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetPreferredMemType(Ceed ceed, CeedMemType *mem_type)

Return Ceed context preferred memory type.

User Functions

Parameters:

ceed – [in] Ceed context to get preferred memory type of
mem_type – [out] Address to save preferred memory type to

Returns:

An error code: 0 - success, otherwise - failure

int CeedIsDeterministic(Ceed ceed, bool *is_deterministic)

Get deterministic status of Ceed.

User Functions

Parameters:

ceed – [in] Ceed
is_deterministic – [out] Variable to store deterministic status

Returns:

An error code: 0 - success, otherwise - failure

int CeedAddJitSourceRoot(Ceed ceed, const char *jit_source_root)

Set additional JiT source root for Ceed.

User Functions

Parameters:

ceed – [inout] Ceed
jit_source_root – [in] Absolute path to additional JiT source directory

Returns:

An error code: 0 - success, otherwise - failure

int CeedView(Ceed ceed, FILE *stream)

View a Ceed.

User Functions

Parameters:

ceed – [in] Ceed to view
stream – [in] Filestream to write to

Returns:

An error code: 0 - success, otherwise - failure

int CeedDestroy(Ceed *ceed)

Destroy a Ceed context.

User Functions

Parameters:

ceed – [inout] Address of Ceed context to destroy

Returns:

An error code: 0 - success, otherwise - failure

const char *CeedErrorFormat(Ceed ceed, const char *format, va_list *args)

int CeedErrorImpl(Ceed ceed, const char *filename, int lineno, const char *func, int ecode, const char *format, ...)

Error handling implementation; use CeedError instead.

Library Developer Functions

int CeedErrorReturn(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args)

Error handler that returns without printing anything.

Pass this to CeedSetErrorHandler() to obtain this error handling behavior.

Library Developer Functions

int CeedErrorStore(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args)

Error handler that stores the error message for future use and returns the error.

Pass this to CeedSetErrorHandler() to obtain this error handling behavior.

Library Developer Functions

int CeedErrorAbort(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args)

Error handler that prints to stderr and aborts.

Pass this to CeedSetErrorHandler() to obtain this error handling behavior.

Library Developer Functions

int CeedErrorExit(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args)

Error handler that prints to stderr and exits.

Pass this to CeedSetErrorHandler() to obtain this error handling behavior.

In contrast to CeedErrorAbort(), this exits without a signal, so atexit() handlers (e.g., as used by gcov) are run.

Library Developer Functions

int CeedSetErrorHandler(Ceed ceed, CeedErrorHandler handler)

Set error handler.

A default error handler is set in CeedInit(). Use this function to change the error handler to CeedErrorReturn(), CeedErrorAbort(), or a user-defined error handler.

Library Developer Functions

int CeedGetErrorMessage(Ceed ceed, const char **err_msg)

Get error message.

The error message is only stored when using the error handler CeedErrorStore()

Library Developer Functions

Parameters:

ceed – [in] Ceed context to retrieve error message
err_msg – [out] Char pointer to hold error message

int CeedResetErrorMessage(Ceed ceed, const char **err_msg)

Restore error message.

The error message is only stored when using the error handler CeedErrorStore()

Library Developer Functions

Parameters:

ceed – [in] Ceed context to restore error message
err_msg – [out] Char pointer that holds error message

int CeedGetVersion(int *major, int *minor, int *patch, bool *release)

Get libCEED library version info.

libCEED version numbers have the form major.minor.patch. Non-release versions may contain unstable interfaces.

The caller may pass NULL for any arguments that are not needed.

Library Developer Functions

See also

CEED_VERSION_GE()

Parameters:

major – [out] Major version of the library
minor – [out] Minor version of the library
patch – [out] Patch (subminor) version of the library
release – [out] True for releases; false for development branches

int CeedGetScalarType(CeedScalarType *scalar_type)

Get libCEED scalar type, such as F64 or F32.

Library Developer Functions

Parameters:

scalar_type – [out] Type of libCEED scalars

Macros

CeedError(ceed, ecode, ...)

Raise an error on ceed object.

See also

CeedSetErrorHandler()

Parameters:

ceed – Ceed library context or NULL
ecode – Error code (int)
... – printf-style format string followed by arguments as needed

CeedPragmaSIMD

This macro provides the appropriate SIMD Pragma for the compilation environment.

Code generation backends may redefine this macro, as needed.

CEED_VERSION_GE(major, minor, patch)

Compile-time check that the the current library version is at least as recent as the specified version.

This macro is typically used in

#if CEED_VERSION_GE(0, 8, 0)
  code path that needs at least 0.8.0
#else
  fallback code for older versions
#endif

A non-release version always compares as positive infinity.

See also

CeedGetVersion()

Parameters:

major – Major version
minor – Minor version
patch – Patch (subminor) version

Typedefs and Enumerations

enum CeedMemType

Specify memory type.

Many Ceed interfaces take or return pointers to memory. This enum is used to specify where the memory being provided or requested must reside.

Values:

enumerator CEED_MEM_HOST: Memory resides on the host.

enumerator CEED_MEM_DEVICE: Memory resides on a device (corresponding to Ceed: core components resource)

enum CeedErrorType

Base scalar type for the library to use: change which header is included to change the precision.

Ceed error code.

This enum is used to specify the type of error returned by a function. A zero error code is success, negative error codes indicate terminal errors and positive error codes indicate nonterminal errors. With nonterminal errors the object state has not been modified, but with terminal errors the object data is likely modified or corrupted.

Values:

enumerator CEED_ERROR_SUCCESS: Success error code.

enumerator CEED_ERROR_MINOR: Minor error, generic.

enumerator CEED_ERROR_DIMENSION: Minor error, dimension mismatch in inputs.

enumerator CEED_ERROR_INCOMPLETE: Minor error, incomplete object setup.

enumerator CEED_ERROR_INCOMPATIBLE: Minor error, incompatible arguments/configuration.

enumerator CEED_ERROR_ACCESS: Minor error, access lock problem.

enumerator CEED_ERROR_MAJOR: Major error, generic.

enumerator CEED_ERROR_BACKEND: Major error, internal backend error.

enumerator CEED_ERROR_UNSUPPORTED: Major error, operation unsupported by current backend.