/simpletypesystem/trunk : contents of libssts/mm.h at revision 163

: (revision 163)

To get this branch, use:

bzr branch
http://gegoxaren.bato24.eu/bzr/simpletypesystem/trunk

#pragma once

/*
Copyright (c) 2013-2016 Gustav Hartvigsson

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
 */

#include "defs.h"

#if USE_GC
#include <gc/gc.h>
#endif

S_BEGIN_DECLS

/**
 * @file 
 * @defgroup MemoryM Memory Management
 * @addtogroup MemoryM
 * @{
 * @brief Memory management stuff.
 *
 * By default libssts does not use a GC, it can be enabled with by setting the
 * USE_GC switch in cmake.
 *
 * Even if you have GC enabled, it is important to make sure that when you do
 * not use the GC it will still cleanup all the pointers.
 *
 * General rule: for every @ref s_malloc() have a @ref s_free() even if you know
 * you are running a GC.
 *
 * The Mark and Sweep method interacts with the the mainloop, freeing the all
 * data marked for freeing in one sweep.
 *
 * In Mark and Sweep s_free adds the pointers to a list of pointers to be freed.
 * This method may cause 'stuttering' in the sweep phase of the loop, and is not
 * immediate. It may fill up memory and then sweep it all in one go.
 *
 * When using the Mark and Sweep method you have to run s_mm_cleanup at the end
 * of the program.
 */

/**
 * Represents what sort of memory management should be used. Used by
 * @ref s_mm_init.
 */
typedef enum {
  S_MM_TYPE_NONE, /*< NONE, use standard. */
  S_MM_TYPE_LIBC, /*< Use libc's malloc/free stuffs */
  S_MM_TYPE_GC, /*< Use libgc's garbage collector. */
  S_MM_TYPE_MARK_AND_SWEEP /*< Use a 'mark and sweep' style system. */
} SMMType;

/**
 * The names of for the enum @ref SMMType.
 */
S_UNUSED static
schar * SMMTypeName[] = {
  "NONE",
  "libc",
  "GC",
  "Mark and Sweep",
  0x0,
  0x0
};

/**
 * Get the name of SMMType.
 *
 * For used in bindings.
 */
S_EXPORTED
schar *
s_mm_type_get_name (SMMType type);

/**
 * Set how memory should be dealth with.
 *
 * Only has effect if you compile with GC enabled.
 */
S_EXPORTED
void
s_mm_init (SMMType type);

/**
 * Clean up memory management.
 * 
 * This should not be called directly, use s_teardown() to instead.
 */
S_HIDDEN
void
s_mm_cleanup ();

/**
 * Get what sort of memory management is used.
 */
S_EXPORTED
SMMType
s_mm_get_type ();

/**
 * By default this is this is just a normal call to malloc. But with
 * GC enabled it will use GC_MALLOC to allocate memory.
 */
S_EXPORTED
spointer
s_malloc (size_t size);

/**
 * by default this acts just as a normal call to free. If GC is enabled this
 * will set the pointer to NULL.
 *
 * In Mark and Sweep mode this will add the pointers to a list of pointers to
 * be freed later in the loop. When this is can not be guaranteed.
 */
S_EXPORTED
void
s_free (spointer pointer);

/**
 * By default this will act just as a normal call to realloc. But if GC is
 * enabled this will use GC_REALLOC.
 */
S_EXPORTED
spointer
s_realloc (spointer pointer, size_t size);

/**
 * By default this acts as a normal call to calloc. If GC in enabled this
 * will just wrap GC_MALLOC, as there is no GC_CALLOC.
 */
S_HIDDEN
spointer
s_calloc (size_t num, size_t size);

/** @} */

/**
 * @}
 */

S_END_DECLS



126.1.1 by Gustav Hartvigsson * Using	1	#pragma once
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	2
130.1.3 by Gustav Hartvigsson * pragma once gawd damn it!	3	/*
	4	Copyright (c) 2013-2016 Gustav Hartvigsson
	5
	6	Permission is hereby granted, free of charge, to any person obtaining a copy
	7	of this software and associated documentation files (the "Software"), to deal
	8	in the Software without restriction, including without limitation the rights
	9	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	10	copies of the Software, and to permit persons to whom the Software is
	11	furnished to do so, subject to the following conditions:
	12
	13	The above copyright notice and this permission notice shall be included in
	14	all copies or substantial portions of the Software.
	15
	16	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	17	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	18	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	19	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	20	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	21	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
	22	THE SOFTWARE.
	23	*/
	24
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	25	#include "defs.h"
	26
	27	#if USE_GC
	28	#include <gc/gc.h>
	29	#endif
	30
	31	S_BEGIN_DECLS
	32
	33	/**
130.1.4 by Gustav Hartvigsson * Inpremented the manual mark and sweep thingys.	34	* @file
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	35	* @defgroup MemoryM Memory Management
	36	* @addtogroup MemoryM
	37	* @{
	38	* @brief Memory management stuff.
	39	*
	40	* By default libssts does not use a GC, it can be enabled with by setting the
	41	* USE_GC switch in cmake.
	42	*
	43	* Even if you have GC enabled, it is important to make sure that when you do
	44	* not use the GC it will still cleanup all the pointers.
	45	*
	46	* General rule: for every @ref s_malloc() have a @ref s_free() even if you know
	47	* you are running a GC.
130.1.1 by Gustav Hartvigsson * Starded work on "mark and sweep" method of memory managment	48	*
130.1.3 by Gustav Hartvigsson * pragma once gawd damn it!	49	* The Mark and Sweep method interacts with the the mainloop, freeing the all
130.1.1 by Gustav Hartvigsson * Starded work on "mark and sweep" method of memory managment	50	* data marked for freeing in one sweep.
130.1.2 by Gustav Hartvigsson * added a lil' bit of information about Mark and Sweep to the documentation in mm.h	51	*
	52	* In Mark and Sweep s_free adds the pointers to a list of pointers to be freed.
	53	* This method may cause 'stuttering' in the sweep phase of the loop, and is not
	54	* immediate. It may fill up memory and then sweep it all in one go.
	55	*
	56	* When using the Mark and Sweep method you have to run s_mm_cleanup at the end
	57	* of the program.
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	58	*/
	59
	60	/**
	61	* Represents what sort of memory management should be used. Used by
	62	* @ref s_mm_init.
	63	*/
	64	typedef enum {
130.1.1 by Gustav Hartvigsson * Starded work on "mark and sweep" method of memory managment	65	S_MM_TYPE_NONE, /< NONE, use standard. /
	66	S_MM_TYPE_LIBC, /< Use libc's malloc/free stuffs /
	67	S_MM_TYPE_GC, /< Use libgc's garbage collector. /
130.1.4 by Gustav Hartvigsson * Inpremented the manual mark and sweep thingys.	68	S_MM_TYPE_MARK_AND_SWEEP /< Use a 'mark and sweep' style system. /
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	69	} SMMType;
	70
	71	/**
	72	* The names of for the enum @ref SMMType.
	73	*/
	74	S_UNUSED static
	75	schar * SMMTypeName[] = {
	76	"NONE",
	77	"libc",
	78	"GC",
130.1.3 by Gustav Hartvigsson * pragma once gawd damn it!	79	"Mark and Sweep",
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	80	0x0,
	81	0x0
	82	};
	83
	84	/**
	85	* Get the name of SMMType.
	86	*
	87	* For used in bindings.
	88	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	89	S_EXPORTED
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	90	schar *
	91	s_mm_type_get_name (SMMType type);
	92
	93	/**
	94	* Set how memory should be dealth with.
	95	*
	96	* Only has effect if you compile with GC enabled.
	97	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	98	S_EXPORTED
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	99	void
	100	s_mm_init (SMMType type);
	101
	102	/**
	103	* Clean up memory management.
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	104	*
	105	* This should not be called directly, use s_teardown() to instead.
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	106	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	107	S_HIDDEN
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	108	void
	109	s_mm_cleanup ();
	110
	111	/**
	112	* Get what sort of memory management is used.
	113	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	114	S_EXPORTED
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	115	SMMType
	116	s_mm_get_type ();
	117
	118	/**
	119	* By default this is this is just a normal call to malloc. But with
	120	* GC enabled it will use GC_MALLOC to allocate memory.
	121	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	122	S_EXPORTED
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	123	spointer
	124	s_malloc (size_t size);
	125
	126	/**
	127	* by default this acts just as a normal call to free. If GC is enabled this
	128	* will set the pointer to NULL.
130.1.3 by Gustav Hartvigsson * pragma once gawd damn it!	129	*
	130	* In Mark and Sweep mode this will add the pointers to a list of pointers to
	131	* be freed later in the loop. When this is can not be guaranteed.
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	132	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	133	S_EXPORTED
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	134	void
	135	s_free (spointer pointer);
	136
	137	/**
	138	* By default this will act just as a normal call to realloc. But if GC is
	139	* enabled this will use GC_REALLOC.
	140	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	141	S_EXPORTED
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	142	spointer
	143	s_realloc (spointer pointer, size_t size);
	144
	145	/**
	146	* By default this acts as a normal call to calloc. If GC in enabled this
	147	* will just wrap GC_MALLOC, as there is no GC_CALLOC.
	148	*/
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	149	S_HIDDEN
121.1.3 by Gustav Hartvigsson * Made the GC switchable at rutime (once) when compiled with S_USE_GC set.	150	spointer
	151	s_calloc (size_t num, size_t size);
	152
	153	/** @} */
	154
	155	/**
	156	* @}
	157	*/
	158
	159	S_END_DECLS
146 by Gustav Hartvigsson * Reorderd includes in SimpleTypeSystem.h	160
	161