Jamoma API  0.6.0.a19
TTEnvironment.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup foundationLibrary
4  *
5  * @brief TTEnvironment is a global object providing information on the environemt.
6  *
7  * @details The global TTEnvironent object maintains all global attributes/settings for the Jamoma environment.
8  * All attribute members of the environment are made public, since essentially every class is a friend.
9  * They should, however, be treated as read-only.
10  *
11  * @author Timothy Place, Nils Peters, Trond Lossius
12  *
13  * @copyright Copyright © 2008, Timothy Place @n
14  * This code is licensed under the terms of the "New BSD License" @n
15  * http://creativecommons.org/licenses/BSD/
16  */
17 
18 
19 #ifndef __TT_ENVIRONMENT_H__
20 #define __TT_ENVIRONMENT_H__
21 
22 #include "TTObjectBase.h"
23 #include "TTHash.h"
24 
25 
26 /** A function pointer for an instance creation function required to be provided by all classes.
27  @ingroup typedefs
28  */
29 typedef TTObjectBase* (*TTObjectBaseInstantiationMethod)(TTSymbol className, const TTValue arguments);
30 
31 /** A function pointer for an instance creation function required to be provided by all classes.
32  @ingroup typedefs
33  */
35 
36 class TTClass;
37 
38 /****************************************************************************************************/
39 // Class Specifications
40 
41 /**
42  The global object maintains all global attributes/settings for the Jamoma environment.
43 
44  All attribute members of the environment are made public, since essentially every class is a friend.
45  They should, however, be treated as read-only.
46 */
47 class TTFOUNDATION_EXPORT TTEnvironment : public TTObjectBase {
48 private:
49  TTHash* classes; ///< A hash keyed on classNames, and returning a TTClassPtr.
50  TTHash* tags; ///< A hash keyed on tag names, which map to TTLists of all classes with that tag name.
51 
52 public:
53  TTBoolean mDebugBasic; ///< Attribute: Basic debug functionality is enabled when true.
54  TTBoolean mDebugMessaging; ///< Attribute: Should all message traffic be logged?
55  TTUInt32 mSampleRate; ///< Current sample rate as understood by the environment as a whole.
56  TTBoolean mBenchmarking; ///< Attribute: Enable benchmarking in TTAudioObject and TTDataObject ?
57 
58 
59  /** Constructor */
60  TTEnvironment();
61 
62 
63  /** Destructor */
64  virtual ~TTEnvironment();
65 
66 
67  /** Retrieve the environment version number.
68  @param anInputValue This is ignored.
69  @param anOutputValue Returns the current version number of the environment.
70  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
71  */
72  TTErr getVersion(const TTValue& anInputValue, TTValue &anOutputValue);
73 
74 
75  /** Register the unit name, and associate it with the constructor to be called.
76  @param className The name of the class to register.
77  @param tags A comma-delimited list of tags in a string.
78  @param anInstantiationMethod A pointer to the C-function that is used to create a new instance of the class.
79  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
80  */
81  TTErr registerClass(const TTSymbol className, const TTString& tagString, const TTObjectBaseInstantiationMethod anInstantiationMethod);
82 
83  // The above creates a class and registers it -- this one just registers a class after it is created.
84  TTErr registerClass(TTClass* theClass);
85 
86 
87  /** Remove a class from the environment's registry.
88  If the executable from which it is loaded is no longer referenced by other classes, then also unload the executable.
89  @param className The name of the class to remove the registry.
90  @return An error code.
91  TTErr unregisterClass(const TTSymbolRef className);
92  */
93 
94 
95  /*
96  TTErr refreshClass(const TTSymbolRef className)
97  {
98  // TODO: cache class Info (like the path of the extension) here
99  unregisterClass(className);
100  // registerClass(className);
101 
102  // TODO: now re-load the DLL.
103  }
104  */
105 
106 
107  /** unload/reload all external classes.
108  NOTE that to do this, we need to keep a piece of information that tags a class as external or internal.
109 
110  This probably means that the hash is going to need to map not to a function pointer,
111  but rather to a struct or an object that keeps all of the class's information bundled together.
112  TTErr refreshAllClasses();
113  */
114 
115 
116  /** Retreive the names of all registered #TTObjectBase classes in the environment.
117  @param anInputValue This is not being used.
118  @param anOutputValue Pass a #TTValue that will be filled with an array of #TTSymbol pointers with the names of the classes.
119  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
120  */
121  TTErr getAllClassNames(const TTValue& anInputValue, TTValue &anOutputValue);
122 
123 
124  /** Retreive the names of all registered #TTObjectBase classes in the environment that
125  are associated with the given tag(s).
126  @param classNames An array of TTSymbols upon return.
127  @param tags An array of tags by which to search the environment's registry.
128  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
129  */
130  TTErr getClassNamesWithTags(TTValue& classNames, const TTValue& searchTags);
131 
132  /** A message-bound version of getClassNamesWithTags() */
133  TTErr getClassNamesForTags(const TTValue& anInputValue, TTValue &anOutputValue);
134 
135  /** Check if a class is registered
136  @param className the name of a class
137  @return #TTErr error code if the class is not registered, else #kTTErrNone.
138  */
139  TTErr isClassRegistered(const TTSymbol& className);
140 
141 
142  /** Create a new instance of a registered #TTObjectBase class.
143  @param className Pass in a #TTSymbol with the name of the unit to load.
144  @param anObject Upon successful return, the value will be set to a #TTObjectBase which is the new instance.
145  If the pointer is passed in as non-NULL then createUnit() will try to free to the
146  existing object to which it points prior to instantiating the new unit.
147  @param anArgument For most audio processing objects, this should be passed the maximum number of channels.
148  For this reason, we overload this method with a TTUint16 argument as a convenience.
149  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
150  */
151  TTErr createInstance(const TTSymbol className, TTObjectBasePtr* anObject, const TTValue& anArgument);
152 
153 
154  /** Create a reference to an object. */
155  TTObjectBasePtr referenceInstance(TTObjectBasePtr anObject);
156 
157 
158  /** Release an instance of a #TTObjectBase class.
159  At the moment this is simply freeing the class, but it may use reference counting in the future
160  (e.g. for TTBuffer references).
161 
162  There are a couple of reasons we want to have this wrapper around the delete operator.
163  - For instrumenting the code to investigate bugs, performance, etc.
164  - So that we can handle any threading, spin-locks, mutexes, or other issues before actually freeing the object.
165  - At some point we may do a more release-like-thing where we reference count for pseudo-garbage-collection.
166 
167  @param unit A pointer to the unit to free.
168  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
169  */
170  TTErr releaseInstance(TTObjectBasePtr* anObject);
171 };
172 
173 
174 /** The environment object has one instance, which is global in scope.
175  */
176 extern TTFOUNDATION_EXPORT TTEnvironment* ttEnvironment;
177 
178 
179 // Public Interface -- REPLACED BY TTOBJECT
180 
181 /** @brief DEPRECATED
182  @deprecated Instead, please use the @n #TTObject constructor as detailed in @ref chapter_usingobjects_lifecycle */
183 TT_DEPRECATED( TTFOUNDATION_EXPORT TTErr TTObjectBaseInstantiate(const TTSymbol className, TTObjectBasePtr* returnedObjectPtr, const TTValue arguments) );
184 TT_DEPRECATED( TTFOUNDATION_EXPORT TTErr TTObjectBaseInstantiate(const TTSymbol className, TTObjectBasePtr* returnedObjectPtr, const TTUInt16 arguments) );
185 
186 /** @brief DEPRECATED
187  @deprecated Instead, most uses can be handled via the @n #TTObject and its = operator */
188 TT_DEPRECATED( TTFOUNDATION_EXPORT TTObjectBasePtr TTObjectBaseReference(TTObjectBasePtr anObject) );
189 
190 /** @brief DEPRECATED
191  @deprecated Instead, please use the @n #TTObject destructor via the delete operator as detailed in @ref chapter_usingobjects_lifecycle */
192 TT_DEPRECATED( TTFOUNDATION_EXPORT TTErr TTObjectBaseRelease(TTObjectBasePtr* anObject) );
193 
194 TTFOUNDATION_EXPORT TTErr TTClassRegister(const TTSymbol className, const TTString& tagString, const TTObjectBaseInstantiationMethod anInstantiationMethod);
195 TTFOUNDATION_EXPORT TTErr TTClassRegister(const TTSymbol className, TTImmutableCString tagString, const TTObjectBaseInstantiationMethod anInstantiationMethod);
196 
197 /** @brief DEPRECATED
198  @deprecated Instead, please use @n TTObject::GetRegisteredClassNames */
199 TT_DEPRECATED( TTFOUNDATION_EXPORT TTErr TTGetRegisteredClassNames(TTValue& classNames) );
200 
201 /** @brief DEPRECATED
202  @deprecated Instead, please use @n TTObject::GetRegisteredClassNamesForTags */
203 TT_DEPRECATED( TTFOUNDATION_EXPORT TTErr TTGetRegisteredClassNamesForTags(TTValue& classNames, const TTValue& searchTags) );
204 
205 #endif // __TT_ENVIRONMENT_H__
206 
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
std::uint16_t TTUInt16
16 bit unsigned integer
Definition: TTBase.h:176
The Jamoma Object Base Class.
TTErr TTObjectBaseRelease(TTObjectBasePtr *anObject)
DEPRECATED.
TTFOUNDATION_EXPORT TTEnvironment * ttEnvironment
The environment object has one instance, which is global in scope.
TTErr TTGetRegisteredClassNames(TTValue &classNames)
DEPRECATED.
TTBoolean mBenchmarking
Attribute: Enable benchmarking in TTAudioObject and TTDataObject ?
Definition: TTEnvironment.h:56
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
TTObjectBase *(* TTObjectBaseInstantiationMethod)(TTSymbol className, const TTValue arguments)
A function pointer for an instance creation function required to be provided by all classes...
Definition: TTEnvironment.h:29
Maintain a collection of TTValue objects indexed by TTSymbol pointers.
Definition: TTHash.h:36
The TTClass object represents a class in the Jamoma environment.
Definition: TTClass.h:32
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTErr TTObjectBaseInstantiate(const TTSymbol className, TTObjectBasePtr *returnedObjectPtr, const TTValue arguments)
DEPRECATED.
TTBoolean mDebugBasic
Attribute: Basic debug functionality is enabled when true.
Definition: TTEnvironment.h:53
TTBoolean mDebugMessaging
Attribute: Should all message traffic be logged?
Definition: TTEnvironment.h:54
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TTErr TTGetRegisteredClassNamesForTags(TTValue &classNames, const TTValue &searchTags)
DEPRECATED.
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178
TTUInt32 mSampleRate
Current sample rate as understood by the environment as a whole.
Definition: TTEnvironment.h:55
TTObjectBasePtr TTObjectBaseReference(TTObjectBasePtr anObject)
DEPRECATED.
The TTString class is used to represent a string.
Definition: TTString.h:34
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
TTErr(* TTExtensionInitializationMethod)()
A function pointer for an instance creation function required to be provided by all classes...
Definition: TTEnvironment.h:34
The global object maintains all global attributes/settings for the Jamoma environment.
Definition: TTEnvironment.h:47