1 // Copyright (c) 2017-2026, Lawrence Livermore National Security, LLC and other CEED contributors. 2 // All Rights Reserved. See the top-level LICENSE and NOTICE files for details. 3 // 4 // SPDX-License-Identifier: BSD-2-Clause 5 // 6 // This file is part of CEED: http://github.com/ceed 7 8 #include <ceed-impl.h> 9 #include <ceed.h> 10 #include <ceed/backend.h> 11 12 /// @file 13 /// Implementation of CeedObject functionality 14 15 /// ---------------------------------------------------------------------------- 16 /// CeedObject Backend API 17 /// ---------------------------------------------------------------------------- 18 /// @addtogroup CeedBackend 19 /// @{ 20 21 /** 22 @brief Create a `CeedObject` 23 24 @param[in] ceed `Ceed` object to reference 25 @param[in] view_function `Ceed*` function for viewing the `obj` 26 @param[out] obj Address of the variable where is `CeedObject` exists 27 28 @return An error code: 0 - success, otherwise - failure 29 30 @ref Backend 31 **/ 32 int CeedObjectCreate(Ceed ceed, int (*view_function)(CeedObject, FILE *), CeedObject obj) { 33 obj->ceed = NULL; 34 if (ceed) CeedCall(CeedReferenceCopy(ceed, &obj->ceed)); 35 obj->ViewFunction = view_function; 36 obj->ref_count = 1; 37 return CEED_ERROR_SUCCESS; 38 } 39 40 /** 41 @brief Increment the reference counter for a `CeedObject` 42 43 @param[in,out] obj `CeedObject` to increment the reference counter 44 45 @return An error code: 0 - success, otherwise - failure 46 47 @ref Backend 48 **/ 49 int CeedObjectReference(CeedObject obj) { 50 obj->ref_count++; 51 return CEED_ERROR_SUCCESS; 52 } 53 54 /** 55 @brief Decrement the reference counter for a `CeedObject` 56 57 @param[in,out] obj `CeedObject` to decrement the reference counter 58 59 @return The new reference count 60 61 @ref Backend 62 **/ 63 int CeedObjectDereference(CeedObject obj) { 64 return --obj->ref_count; // prefix notation, to get new number of references 65 } 66 67 /** 68 @brief Destroy a @ref CeedObject 69 70 @param[in,out] obj `CeedObject` to destroy 71 72 @return An error code: 0 - success, otherwise - failure 73 74 @ref Backend 75 **/ 76 int CeedObjectDestroy(CeedObject obj) { 77 CeedCheck(obj->ref_count == 0, CeedObjectReturnCeed(obj), CEED_ERROR_ACCESS, "Cannot destroy CeedObject, it is still referenced by another object"); 78 if (obj->ceed) CeedCall(CeedDestroy(&obj->ceed)); 79 return CEED_ERROR_SUCCESS; 80 } 81 82 /// @} 83 84 /// ---------------------------------------------------------------------------- 85 /// CeedObject Public API 86 /// ---------------------------------------------------------------------------- 87 /// @addtogroup CeedUser 88 /// @{ 89 90 /** 91 @brief View a `CeedObject` 92 93 @param[in] obj `CeedObject` to view 94 @param[in] stream Stream to view to, e.g., `stdout` 95 96 @return An error code: 0 - success, otherwise - failure 97 98 @ref User 99 **/ 100 int CeedObjectView(CeedObject obj, FILE *stream) { 101 if (obj->ViewFunction) CeedCall(obj->ViewFunction(obj, stream)); 102 return CEED_ERROR_SUCCESS; 103 } 104 105 /** 106 @brief Set the number of tabs to indent for @ref CeedObjectView() output 107 108 @param[in] obj `CeedObject` to set the number of view tabs 109 @param[in] num_tabs Number of view tabs to set 110 111 @return Error code: 0 - success, otherwise - failure 112 113 @ref User 114 **/ 115 int CeedObjectSetNumViewTabs(CeedObject obj, CeedInt num_tabs) { 116 CeedCheck(num_tabs >= 0, CeedObjectReturnCeed(obj), CEED_ERROR_MINOR, "Number of view tabs must be non-negative"); 117 obj->num_view_tabs = num_tabs; 118 return CEED_ERROR_SUCCESS; 119 } 120 121 /** 122 @brief Get the number of tabs to indent for @ref CeedObjectView() output 123 124 @param[in] obj `CeedObject` to get the number of view tabs 125 @param[out] num_tabs Number of view tabs 126 127 @return Error code: 0 - success, otherwise - failure 128 129 @ref User 130 **/ 131 int CeedObjectGetNumViewTabs(CeedObject obj, CeedInt *num_tabs) { 132 *num_tabs = obj->num_view_tabs; 133 return CEED_ERROR_SUCCESS; 134 } 135 136 /** 137 @brief Get the `Ceed` associated with a `CeedObject` 138 139 @param[in] obj `CeedObject` 140 @param[out] ceed Variable to store `Ceed` 141 142 @return An error code: 0 - success, otherwise - failure 143 144 @ref Advanced 145 **/ 146 int CeedObjectGetCeed(CeedObject obj, Ceed *ceed) { 147 *ceed = NULL; 148 CeedCall(CeedReferenceCopy(CeedObjectReturnCeed(obj), ceed)); 149 return CEED_ERROR_SUCCESS; 150 } 151 152 /** 153 @brief Return the `Ceed` associated with a `CeedObject` 154 155 @param[in] obj `CeedObject` 156 157 @return `Ceed` associated with the `basis` 158 159 @ref Advanced 160 **/ 161 Ceed CeedObjectReturnCeed(CeedObject obj) { return (obj->ceed) ? obj->ceed : (Ceed)obj; } 162 163 /// @} 164