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
-
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
untilop1
has completed.- Todo:
The current implementation is overly strict, offering equivalent semantics to CEED_REQUEST_IMMEDIATE.
See also
-
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 notfree()
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
- 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 thatceed_copy
is a pointer to a Ceed context. This Ceed context will be destroyed ifceed_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
-
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
- 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
- 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
- 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)
-
enumerator CEED_MEM_HOST
-
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.
-
enumerator CEED_ERROR_SUCCESS