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[in] destroy_function `Ceed*` function for destroying the `obj` 27 @param[out] obj Address of the variable where is `CeedObject` exists 28 29 @return An error code: 0 - success, otherwise - failure 30 31 @ref Backend 32 **/ 33 int CeedObjectCreate(Ceed ceed, int (*view_function)(CeedObject, FILE *), int (*destroy_function)(CeedObject *), CeedObject obj) { 34 obj->ceed = NULL; 35 if (ceed) CeedCall(CeedReferenceCopy(ceed, &obj->ceed)); 36 obj->View = view_function; 37 CeedCheck(destroy_function, CeedObjectReturnCeed(obj), CEED_ERROR_UNSUPPORTED, "Must provide destroy function to create CeedObject"); 38 obj->Destroy = destroy_function; 39 obj->ref_count = 1; 40 return CEED_ERROR_SUCCESS; 41 } 42 43 /** 44 @brief Increment the reference counter for a `CeedObject` 45 46 @param[in,out] obj `CeedObject` to increment the reference counter 47 48 @return An error code: 0 - success, otherwise - failure 49 50 @ref Backend 51 **/ 52 int CeedObjectReference(CeedObject obj) { 53 obj->ref_count++; 54 return CEED_ERROR_SUCCESS; 55 } 56 57 /** 58 @brief Decrement the reference counter for a `CeedObject` 59 60 @param[in,out] obj `CeedObject` to decrement the reference counter 61 62 @return The new reference count 63 64 @ref Backend 65 **/ 66 int CeedObjectDereference(CeedObject obj) { 67 return --obj->ref_count; // prefix notation, to get new number of references 68 } 69 70 /** 71 @brief Destroy a @ref CeedObject 72 73 @param[in,out] obj `CeedObject` to destroy 74 75 @return An error code: 0 - success, otherwise - failure 76 77 @ref Backend 78 **/ 79 int CeedObjectDestroy_Private(CeedObject obj) { 80 CeedCheck(obj->ref_count == 0, CeedObjectReturnCeed(obj), CEED_ERROR_UNSUPPORTED, 81 "Cannot destroy CeedObject, it is still referenced by another object"); 82 if (obj->ceed) CeedCall(CeedDestroy(&obj->ceed)); 83 return CEED_ERROR_SUCCESS; 84 } 85 86 /// @} 87 88 /// ---------------------------------------------------------------------------- 89 /// CeedObject Public API 90 /// ---------------------------------------------------------------------------- 91 /// @addtogroup CeedUser 92 /// @{ 93 94 /** 95 @brief View a `CeedObject` 96 97 @param[in] obj `CeedObject` to view 98 @param[in] stream Stream to view to, e.g., `stdout` 99 100 @return An error code: 0 - success, otherwise - failure 101 102 @ref User 103 **/ 104 int CeedObjectView(CeedObject obj, FILE *stream) { 105 if (obj->View) CeedCall(obj->View(obj, stream)); 106 return CEED_ERROR_SUCCESS; 107 } 108 109 /** 110 @brief Set the number of tabs to indent for @ref CeedObjectView() output 111 112 @param[in] obj `CeedObject` to set the number of view tabs 113 @param[in] num_tabs Number of view tabs to set 114 115 @return Error code: 0 - success, otherwise - failure 116 117 @ref User 118 **/ 119 int CeedObjectSetNumViewTabs(CeedObject obj, CeedInt num_tabs) { 120 CeedCheck(num_tabs >= 0, CeedObjectReturnCeed(obj), CEED_ERROR_MINOR, "Number of view tabs must be non-negative"); 121 obj->num_view_tabs = num_tabs; 122 return CEED_ERROR_SUCCESS; 123 } 124 125 /** 126 @brief Get the number of tabs to indent for @ref CeedObjectView() output 127 128 @param[in] obj `CeedObject` to get the number of view tabs 129 @param[out] num_tabs Number of view tabs 130 131 @return Error code: 0 - success, otherwise - failure 132 133 @ref User 134 **/ 135 int CeedObjectGetNumViewTabs(CeedObject obj, CeedInt *num_tabs) { 136 *num_tabs = obj->num_view_tabs; 137 return CEED_ERROR_SUCCESS; 138 } 139 140 /** 141 @brief Get the `Ceed` associated with a `CeedObject` 142 143 @param[in] obj `CeedObject` 144 @param[out] ceed Variable to store `Ceed` 145 146 @return An error code: 0 - success, otherwise - failure 147 148 @ref Advanced 149 **/ 150 int CeedObjectGetCeed(CeedObject obj, Ceed *ceed) { 151 *ceed = NULL; 152 CeedCall(CeedReferenceCopy(CeedObjectReturnCeed(obj), ceed)); 153 return CEED_ERROR_SUCCESS; 154 } 155 156 /** 157 @brief Return the `Ceed` associated with a `CeedObject` 158 159 @param[in] obj `CeedObject` 160 161 @return `Ceed` associated with the `basis` 162 163 @ref Advanced 164 **/ 165 Ceed CeedObjectReturnCeed(CeedObject obj) { return (obj->ceed) ? obj->ceed : (Ceed)obj; } 166 167 /** 168 @brief Destroy a @ref CeedObject 169 170 @param[in,out] obj Address of `CeedObject` to destroy 171 172 @return An error code: 0 - success, otherwise - failure 173 174 @ref Backend 175 **/ 176 int CeedObjectDestroy(CeedObject *obj) { 177 CeedCall((*obj)->Destroy(obj)); 178 return CEED_ERROR_SUCCESS; 179 } 180 181 /// @} 182