00001 /* Part of the culibs project, <http://www.eideticdew.org/culibs/>. 00002 * Copyright (C) 2005--2007 Petter Urkedal <urkedal@nbi.dk> 00003 * 00004 * This program is free software: you can redistribute it and/or modify 00005 * it under the terms of the GNU General Public License as published by 00006 * the Free Software Foundation, either version 3 of the License, or 00007 * (at your option) any later version. 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program. If not, see <http://www.gnu.org/licenses/>. 00016 */ 00017 00018 #ifndef CUOO_PROP_H 00019 #define CUOO_PROP_H 00020 00021 #include <cuoo/fwd.h> 00022 #include <cucon/pmap.h> 00023 #include <cu/rarex.h> 00024 00025 CU_BEGIN_DECLARATIONS 00026 /*!\defgroup cuoo_prop cuoo/prop.h: Thread-Safe Properties 00027 * @{ \ingroup cuoo_mod 00028 * 00029 * \note Storing the property globally will prevent the expressions 00030 * and values from being recycled by the garbage collector. For variables 00031 * the alternative is to use \c cuex_pvar_t which has internally stored 00032 * properties. Local properties which is used within a single thread are 00033 * more efficiently stored in a \c cucon_pmap_t. */ 00034 00035 struct cuoo_prop 00036 { 00037 struct cucon_pmap pmap; 00038 cu_rarex_t rarex; 00039 }; 00040 00041 /* Construct a property. */ 00042 void cuoo_prop_cct(cuoo_prop_t prop); 00043 cuoo_prop_t cuoo_prop_new(void); 00044 00045 00046 /* Easy Interface 00047 * -------------- 00048 * 00049 * Set pre-constructed properties and get them without worrying about 00050 * locking. No unlocked modification to the value after setting it, but you 00051 * can replace it. */ 00052 00053 /*!Sets a pointer value for \a prop of \a ex. Returns true iff the 00054 * property did not exist in advance for \a ex. */ 00055 cu_bool_t cuoo_prop_replace_ptr(cuoo_prop_t key, cuex_t ex, void *value); 00056 00057 /*!Sets a pointer value for \a prop of \a ex and returns true iff the 00058 * property did not exist in advance for \a ex. */ 00059 cu_bool_t cuoo_prop_condset_ptr(cuoo_prop_t key, cuex_t ex, void *value); 00060 00061 /*!Sets a pointer value for \a prop of \a ex. Fails with an error if 00062 * property exists for \a ex. */ 00063 void cuoo_prop_define_ptr(cuoo_prop_t key, cuex_t ex, void *value); 00064 00065 /*!Returns the value for \a prop of \a ex, assuming the slot contains a 00066 * pointer. */ 00067 void *cuoo_prop_get_ptr(cuoo_prop_t key, cuex_t ex); 00068 00069 00070 /* Property-Slot Interface 00071 * ----------------------- 00072 * 00073 * Set and modify properties in internal value slots at the expense of 00074 * dealing with locking. */ 00075 00076 /*!Set '*slot' to point to the property \a prop of \a ex, allocating a 00077 * slot of size \a size if it does not yet exist. Returns true iff the 00078 * property does not exist, but locks \a prop in either case. */ 00079 cu_bool_t cuoo_prop_set_mem_lock(cuoo_prop_t key, cuex_t ex, 00080 size_t size, cu_ptr_ptr_t slot); 00081 00082 /*!Set '*slot' to point to the property \a prop of \a ex, allocating a 00083 * slot of size \a size if it does not yet exist. Returns true and locks 00084 * \a prop iff the property does not exists. */ 00085 cu_bool_t cuoo_prop_set_mem_condlock(cuoo_prop_t key, cuex_t ex, 00086 size_t size, cu_ptr_ptr_t slot); 00087 00088 /*!Call this when you are done modifying a slot obtained by a call to 00089 * \ref cuoo_prop_set_mem_lock or a true-returning call to 00090 * \ref cuoo_prop_set_mem_condlock. */ 00091 CU_SINLINE void cuoo_prop_set_mem_unlock(cuoo_prop_t key, cuex_t ex) 00092 { cu_rarex_unlock_write(&key->rarex); } 00093 00094 /*!Return property \a key of \a ex and lock \a key for reading even if NULL 00095 * is returned. */ 00096 void *cuoo_prop_get_mem_lock(cuoo_prop_t key, cuex_t ex); 00097 00098 /*!If \a ex has a property \a key, (read-)lock it and return a pointer 00099 * to its slot. */ 00100 void *cuoo_prop_get_mem_condlock(cuoo_prop_t key, cuex_t ex); 00101 00102 /*!Call this after reading a slot returned by a call to 00103 * \ref cuoo_prop_get_mem_condlock which returned non-NULL. */ 00104 CU_SINLINE void cuoo_prop_get_mem_unlock(cuoo_prop_t key, cuex_t ex) 00105 { cu_rarex_unlock_read(&key->rarex); } 00106 00107 /*!@}*/ 00108 CU_END_DECLARATIONS 00109 00110 #endif