Ceed

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

Base library resources

typedef struct Ceed_private *Ceed

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 – [inout] 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 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 context.

User Functions

Parameters:

  • ceed – [in] Ceed context

  • 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 context.

User Functions

Parameters:

  • ceed – [inout] Ceed context

  • 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

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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

Get libCEED library version information.

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

Returns:

An error code: 0 - success, otherwise - failure

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

Returns:

An error code: 0 - success, otherwise - failure

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.