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
-
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 – [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 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
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 streamhandle – [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 aCeed
context. ThisCeed
context will be destroyed if*ceed_copy
is the only reference to thisCeed
context.User Functions
- Parameters:
ceed – [in]
Ceed
context to copy reference toceed_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 ofresource – [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 ofmem_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
contextis_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
contextjit_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 viewstream – [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
-
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 messageerr_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 messageerr_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
- 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
- Parameters:
ceed –
Ceed
library context orNULL
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