added kdenlive
[feisty_meow.git] / nucleus / library / structures / static_memory_gremlin.h
1 #ifndef STATIC_MEMORY_GREMLIN_CLASS
2 #define STATIC_MEMORY_GREMLIN_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : static_memory_gremlin                                             *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1992-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include <basis/contracts.h>
19 #include <basis/enhance_cpp.h>
20 #include <basis/mutex.h>
21
22 namespace structures {
23
24 // forward declarations.
25 class gremlin_object_record;
26
27 //! Holds onto memory chunks that are allocated globally within the program.
28 /*!
29   The objects managed by the gremlin do not get destroyed until after the
30   program begins shutting down.  This file also provides the SAFE_STATIC macros
31   that can be used for allocating static objects safely in a multi-threaded
32   program.
33 */
34
35 class static_memory_gremlin : public virtual basis::nameable
36 {
37 public:
38   static_memory_gremlin();
39
40   ~static_memory_gremlin();
41     /*!< when destroyed, it is assumed that the program's lifetime is over and
42     all objects stored here are now unnecessary.  this implements a
43     regenerative scheme for when static shutdowns occur out of order; if an
44     object has already been destroyed, it is recreated for the purposes of
45     other statics being shutdown.  eventually this should stabilize since
46     it's completely unacceptable for static objects to depend on each other
47     in a cycle. */
48
49   DEFINE_CLASS_NAME("static_memory_gremlin");
50
51   static bool __program_is_dying();
52     //!< Reports whether the program is shutting down currently.
53     /*!< If this flag is true, then code should generally just return without
54     doing anything where possible.  It's especially important for long
55     running loops or active threads to stop if they see this, although
56     the normal program exit processes usually make it unnecessary. */
57
58   static static_memory_gremlin &__hoople_globals();
59     //!< Holds onto objects that have been allocated in a program-wide scope.
60     /*!< These objects will have a lifetime up to the point of normal static
61     object destruction and then they will be cleaned up. */
62
63   static basis::mutex &__memory_gremlin_synchronizer();
64     //!< private object for static_memory_gremlin's use only.
65
66   void enable_debugging(bool verbose) { c_show_debugging = verbose; }
67     //!< if "verbose" is true, then the object will produce a noisy log.
68
69   bool put(const char *unique_name, basis::root_object *ptr);
70     //!< adds a "ptr" to the set of static objects under the "unique_name".
71     /*!< the name must really be unique or objects will collide.  we recommend
72     using an identifier based on a line number and filename where the static
73     is going to be placed (see the safe static implementation below). */
74
75   basis::root_object *get(const char *unique_name);
76     //!< locates the pointer held for the "unique_name", if any.
77     /*!< if no pointer exists, then NULL_POINTER is returned.  NOTE: the returned
78     pointer must not be destroyed, since the object could be used at any time
79     during the program's lifetime. */
80
81   const char *find(const basis::root_object *ptr);
82     //!< locates the name for "ptr" in our objects.
83     /*!< if it does not exist, then NULL_POINTER is returned. */
84
85   void ensure_space_exists();
86     /*!< makes sure that the list of objects is large enough to contain all of
87     the identifiers that have been issued. */
88
89 private:
90   basis::mutex c_lock;  //!< protects object's state.
91   int c_top_index;  //!< top place that's occupied in the list.
92   int c_actual_size;  //!< the real number of indices in list.
93   gremlin_object_record **c_pointers;  //!< storage for the static pointers.
94   bool c_show_debugging;  //!< if true, then the object will log noisily.
95
96   int locate(const char *unique_name);
97     //!< returns the index number of the "unique_name".
98 };
99
100 //////////////
101
102 //! Statically defines a singleton object whose scope is the program's lifetime.
103 /*!
104   SAFE_STATIC is a macro that dynamically creates a function returning a particular
105   data type.  the object is allocated statically, so that the same object will be
106   returned ever after until the program is shut down.  the allocation is guarded so
107   that multiple threads cannot create conflicting static objects.
108
109   note: in ms-win32, if you use this macro in a static library (rather than
110   a DLL), then the heap context is different.  thus you could actually have
111   multiple copies of the underlying object.  if the object is supposed to
112   be global and unique, then that's a problem.  relocating the definitions
113   to a dll while keeping declarations in the static lib works (see the
114   program wide logger approach in <application/program_wide_logger.h>).
115     "type" is the object class to return.
116     "func_name" is the function to be created.
117     "parms" must be a list of parameters in parentheses or nothing.
118
119   example usage: @code
120   SAFE_STATIC(connection_table, conntab, (parm1, parm2)) @endcode
121   will define a function: connection_table &conntab()
122   that returns a connection table object which has been created safely,
123   given that the main synchronizer was called from the main thread at least
124   once.  @code
125   SAFE_STATIC(astring, static_string_doodle, ) @endcode
126   will define a static astring object named "static_string_doodle" that uses
127   the default constructor for astrings.
128 */
129 #define SAFE_STATIC(type, func_name, parms) \
130   type &func_name() { SAFE_STATIC_IMPLEMENTATION(type, parms, __LINE__); }
131
132 //! this version returns a constant object instead.
133 #define SAFE_STATIC_CONST(type, func_name, parms) \
134   const type &func_name() \
135   { SAFE_STATIC_IMPLEMENTATION(type, parms, __LINE__); }
136
137 //! Statically defines a string for the rest of the program's life.
138 /*! This macro can be used to make functions returning a string a little
139 simpler.  This can only be used when the string is constant.  The usual way
140 to use this macro is in a function that returns a constant reference to a
141 string.  The macro allocates the string to be returned statically so that all
142 future calls will refer to the stored string rather than recreating it again. */
143 #define STATIC_STRING(str) \
144   SAFE_STATIC_IMPLEMENTATION(astring, (str), __LINE__)
145
146 //////////////
147
148 //! this macro creates a unique const char pointer based on file location.
149 #define UNIQUE_NAME_BASED_ON_SOURCE(name, linenum) \
150   static const char *name = "file:" __FILE__ ":line:" #linenum
151
152 //! this blob is just a chunk of macro implementation for SAFE_STATIC...
153 /*! if the static object isn't initialized yet, we'll create it and store it
154 in the static_memory_gremlin.  we make sure that the program isn't shutting
155 down, because that imposes a new requirement--previously created statics might
156 have already been destroyed.  thus, during the program shutdown, we carefully
157 recreate any objects that were already toast. */
158 #define SAFE_STATIC_IMPLEMENTATION(type, parms, linenum) \
159 /*hmmm: bring all this back.*/ \
160 /*  const char *func = "allocation"; */ \
161 /*  frame_tracking_instance __trail_of_function("safe_static", func, \
162       __FILE__, __LINE__, true); */ \
163   UNIQUE_NAME_BASED_ON_SOURCE(__uid_name, linenum); \
164 /*  program_wide_memories(); */ \
165   static basis::root_object *_hidden = NULL_POINTER; \
166   /* if haven't initialized yet, then definitely need to lock carefully. */ \
167   if (structures::static_memory_gremlin::__program_is_dying() || !_hidden) { \
168     basis::auto_synchronizer l(structures::static_memory_gremlin::__memory_gremlin_synchronizer()); \
169     if (structures::static_memory_gremlin::__program_is_dying()) { \
170       /* we can't rely on the pointer since we're shutting down currently. */ \
171       _hidden = structures::static_memory_gremlin::__hoople_globals().get(__uid_name); \
172     } \
173     if (!_hidden) {  /* make sure no one scooped us. */ \
174       /* try to retrieve an existing one first and use it if there. */ \
175       _hidden = structures::static_memory_gremlin::__hoople_globals().get(__uid_name); \
176       if (!_hidden) { \
177         _hidden = new type parms ; /* create the object finally. */ \
178         /* store our object using the unique name for it. */ \
179         if (!structures::static_memory_gremlin::__hoople_globals().put(__uid_name, _hidden)) { \
180           /* we failed to allocate space.  this is serious. */ \
181           throw __uid_name; \
182         } \
183       } \
184     } \
185   } \
186   if (!_hidden) { \
187     /* grab the pointer that was stored, in case we're late getting here. */ \
188     /* another thread might have scooped the object creation. */ \
189     _hidden = structures::static_memory_gremlin::__hoople_globals().get(__uid_name); \
190   } \
191   return *dynamic_cast<type *>(_hidden)
192
193 // historical note: the SAFE_STATIC approach has existed since about 1998.
194 // however, the static_memory_gremlin's role in this started much later.
195
196 } //namespace.
197
198 #endif
199