1 /* 2 Copyright 2020 Northern.tech AS 3 4 This file is part of CFEngine 3 - written and maintained by Northern.tech AS. 5 6 This program is free software; you can redistribute it and/or modify it 7 under the terms of the GNU General Public License as published by the 8 Free Software Foundation; version 3. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program; if not, write to the Free Software 17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 18 19 To the extent this program is licensed as part of the Enterprise 20 versions of CFEngine, the applicable Commercial Open Source License 21 (COSL) may apply to this file if you as a licensee so wish it. See 22 included file COSL.txt. 23 */ 24 25 #ifndef CFENGINE_REFCOUNT_H 26 #define CFENGINE_REFCOUNT_H 27 28 #include <platform.h> 29 /** 30 @brief Simple reference count implementation. 31 32 Reference counting helps to keep track of elements and avoid unnecessary duplication. 33 In C we need to manually keep track of the users, while in C++ this is implicitly done 34 by the "this" pointer. If we don't do that and we just count how many users we have, 35 we risk multiples attach or detach. We need one way to find out who is connected to 36 the refcount so we can act properly. 37 */ 38 struct RefCountNode { 39 struct RefCountNode *next; 40 struct RefCountNode *previous; 41 void *user; 42 }; 43 typedef struct RefCountNode RefCountNode; 44 45 struct RefCount { 46 // Normally one unless we are shared. 47 unsigned int user_count; 48 RefCountNode *users; 49 RefCountNode *last; 50 }; 51 typedef struct RefCount RefCount; 52 53 /** 54 @brief Initializes a refcount structure. 55 @param ref RefCount structure to be initialized. 56 */ 57 void RefCountNew(RefCount **ref); 58 /** 59 @brief Destroys a refcount structure. 60 @param ref RefCount structure to be destroyed. 61 */ 62 void RefCountDestroy(RefCount **ref); 63 /** 64 @brief Attaches a data structure to a given RefCount structure. 65 Attaching refers to the fact that the container is using a data structure that might be shared by others. 66 This should be called before using the data structure so everybody is aware of the new holder. 67 @param ref RefCountr structure 68 @param owner Data structure to be attached. 69 */ 70 void RefCountAttach(RefCount *ref, void *owner); 71 /** 72 @brief Detaches a data structure from a given RefCount structure. 73 Detaching should be called after the container has copied the data structure. As long as the container is 74 still using the data structure it should not detach from the reference counting. Otherwise this might lead 75 to undesired side effects. 76 @param ref RefCountr structure 77 @param owner Data structure to be detached. 78 */ 79 void RefCountDetach(RefCount *ref, void *owner); 80 /** 81 @brief Simple check to see if a given data structure is shared. 82 @param ref RefCount structure. 83 @return True if shared, false otherwise. 84 */ 85 bool RefCountIsShared(RefCount *ref); 86 /** 87 @brief Compares two RefCount structures. 88 @param a 89 @param b 90 @return True if a and b point to the same object, false otherwise. 91 @remarks This function is needed in order to speed up comparisons of complex 92 data structures. If the RefCount objects of the two structures are the same, 93 then most likely the structures are the same. 94 */ 95 bool RefCountIsEqual(RefCount *a, RefCount *b); 96 97 #endif // CFENGINE_REFCOUNT_H 98