libpeak-0.1.2/peak/alloc.h

/* PEAK Library
 *
 * Copyright (c) 2003
 *      Stephane Thiell <mbuna@bugged.org>. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * $Id: alloc.h,v 1.1.1.1 2003/12/30 02:29:05 mbuna Exp $
 */
#ifndef INCLUDED_PEAK_ALLOC_H_
#define INCLUDED_PEAK_ALLOC_H_

/*!
 * @defgroup alloc Allocation
 * 
 * @par
 * Peak's allocation mechanism uses the standard malloc/free pair but can be
 * configured as wish with peak_alloc_configure() providing your
 * own allocation and deallocation primitives.
 * 
 * @par
 * Although written in C, peak is object oriented and features a
 * lightweight support for reference counting in all peak objects. This
 * module offers access to the peak_retain() an peak_release() method.\n
 * Strings, however, are normal C strings and not wrapped by the peak
 * library. For convenience, a peak_strdup() method is provided as well.
 */

#include <sys/types.h>

/*!
 * @ingroup alloc
 * @brief Malloc-like function pointer type.
 */
typedef void * (*peak_alloc_malloc_func)(size_t size);

/*!
 * @ingroup alloc
 * @brief Free-like function pointer type.
 */
typedef void (*peak_alloc_free_func)(void *p);

#if defined(__cplusplus)
extern "C" {
#endif

/*!
 * @ingroup alloc
 * @brief Configure peak's allocation for your program.
 * 
 * Pointed functions must properly align memory and be thread-safe like
 * malloc() and free()...
 * 
 * @param malloc_fun A pointer to your custom malloc-like function.
 * @param free_fun   A pointer to your custom free-like function.
 */
extern void peak_alloc_configure(peak_alloc_malloc_func malloc_fun,
                                 peak_alloc_free_func free_fun);

/*!
 * @ingroup alloc
 * @brief Allocate memory.
 * 
 * @param size Number of bytes of memory to allocate.
 * 
 * @result A pointer to the fresh allocated memory.
 */
extern void * peak_allocate(size_t size);

/*!
 * @ingroup alloc
 * @brief Free memory.
 * 
 * @param ptr Pointer to the memory space to deallocate.
 */
extern void peak_deallocate(void *ptr);

/*!
 * @ingroup alloc
 * @brief Copy a string.
 * 
 * @param str The string to copy/duplicate.
 * 
 * @result A pointer to a new allocated copy of the string. It should be
 *         passed to peak_deallocate() if you want to free it.
 */
extern char * peak_strdup(const char *str);

/*!
 * @ingroup alloc
 * @brief Retain a peak object.
 * 
 * Increase the reference count of the object \a obj.
 * 
 * @param obj Any peak object.
 * 
 * @result For convenience, a pointer to \a obj.
 */
extern void * peak_retain(void *obj);


/*!
 * @ingroup alloc
 * @brief Release a peak object.
 * 
 * Decrease the reference count of the object \a obj. If the refcount is 0, 
 * the object is deallocated.
 * 
 * @param obj Any peak object.
 */
extern void peak_release(void *obj);


/*!
 * @ingroup alloc
 * @brief Get the retain count of a peak object.
 * 
 * @param obj Any peak object.
 *
 * @result Retain count or -1 for constant objects.
 */
extern int peak_get_retcnt(void *obj);


#if defined(__cplusplus)
}
#endif


#endif /* INCLUDED_PEAK_ALLOC_H_ */
Revision:	3251
Committed:	Wed Apr 2 16:58:30 2014 UTC (11 years, 4 months ago) by michael
Content type:	text/x-chdr
File size:	4332 byte(s)
Log Message:	- Imported libpeak-0.1.2
#	Content
1	/* PEAK Library
2	*
3	* Copyright (c) 2003
4	* Stephane Thiell <mbuna@bugged.org>. All rights reserved.
5	*
6	* Redistribution and use in source and binary forms, with or without
7	* modification, are permitted provided that the following conditions
8	* are met:
9	*
10	* 1. Redistributions of source code must retain the above copyright
11	* notice, this list of conditions and the following disclaimer.
12	*
13	* 2. Redistributions in binary form must reproduce the above copyright
14	* notice, this list of conditions and the following disclaimer in the
15	* documentation and/or other materials provided with the distribution.
16	*
17	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19	* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20	* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
21	* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22	* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23	* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
24	* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
25	* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
26	* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
27	* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28	*
29	* $Id: alloc.h,v 1.1.1.1 2003/12/30 02:29:05 mbuna Exp $
30	*/
31	#ifndef INCLUDED_PEAK_ALLOC_H_
32	#define INCLUDED_PEAK_ALLOC_H_
33
34	/*!
35	* @defgroup alloc Allocation
36	*
37	* @par
38	* Peak's allocation mechanism uses the standard malloc/free pair but can be
39	* configured as wish with peak_alloc_configure() providing your
40	* own allocation and deallocation primitives.
41	*
42	* @par
43	* Although written in C, peak is object oriented and features a
44	* lightweight support for reference counting in all peak objects. This
45	* module offers access to the peak_retain() an peak_release() method.\n
46	* Strings, however, are normal C strings and not wrapped by the peak
47	* library. For convenience, a peak_strdup() method is provided as well.
48	*/
49
50	#include <sys/types.h>
51
52	/*!
53	* @ingroup alloc
54	* @brief Malloc-like function pointer type.
55	*/
56	typedef void * (*peak_alloc_malloc_func)(size_t size);
57
58	/*!
59	* @ingroup alloc
60	* @brief Free-like function pointer type.
61	*/
62	typedef void (peak_alloc_free_func)(void p);
63
64	#if defined(__cplusplus)
65	extern "C" {
66	#endif
67
68	/*!
69	* @ingroup alloc
70	* @brief Configure peak's allocation for your program.
71	*
72	* Pointed functions must properly align memory and be thread-safe like
73	* malloc() and free()...
74	*
75	* @param malloc_fun A pointer to your custom malloc-like function.
76	* @param free_fun A pointer to your custom free-like function.
77	*/
78	extern void peak_alloc_configure(peak_alloc_malloc_func malloc_fun,
79	peak_alloc_free_func free_fun);
80
81	/*!
82	* @ingroup alloc
83	* @brief Allocate memory.
84	*
85	* @param size Number of bytes of memory to allocate.
86	*
87	* @result A pointer to the fresh allocated memory.
88	*/
89	extern void * peak_allocate(size_t size);
90
91	/*!
92	* @ingroup alloc
93	* @brief Free memory.
94	*
95	* @param ptr Pointer to the memory space to deallocate.
96	*/
97	extern void peak_deallocate(void *ptr);
98
99	/*!
100	* @ingroup alloc
101	* @brief Copy a string.
102	*
103	* @param str The string to copy/duplicate.
104	*
105	* @result A pointer to a new allocated copy of the string. It should be
106	* passed to peak_deallocate() if you want to free it.
107	*/
108	extern char * peak_strdup(const char *str);
109
110	/*!
111	* @ingroup alloc
112	* @brief Retain a peak object.
113	*
114	* Increase the reference count of the object \a obj.
115	*
116	* @param obj Any peak object.
117	*
118	* @result For convenience, a pointer to \a obj.
119	*/
120	extern void * peak_retain(void *obj);
121
122
123	/*!
124	* @ingroup alloc
125	* @brief Release a peak object.
126	*
127	* Decrease the reference count of the object \a obj. If the refcount is 0,
128	* the object is deallocated.
129	*
130	* @param obj Any peak object.
131	*/
132	extern void peak_release(void *obj);
133
134
135	/*!
136	* @ingroup alloc
137	* @brief Get the retain count of a peak object.
138	*
139	* @param obj Any peak object.
140	*
141	* @result Retain count or -1 for constant objects.
142	*/
143	extern int peak_get_retcnt(void *obj);
144
145
146	#if defined(__cplusplus)
147	}
148	#endif
149
150
151	#endif /* INCLUDED_PEAK_ALLOC_H_ */