/xbmc/visualizations/Vortex/angelscript/docs/doxygen/source/doc_adv_template.h

  1/**
  2
  3\page doc_adv_template Template types
  4
  5A template type in AngelScript works similarly to how templates work in C++. The scripts 
  6will be able to instanciate different forms of the template type by specifying which subtype 
  7that should be used. The methods for the instance will then be adapted to this subtype, so
  8that the correct handling of parameters and return types will be applied.
  9
 10The implementation of the template type is not a C++ template though, instead it must 
 11be implemented as a generic class that can determine what to do dynamically at runtime based
 12on the subtype for which it was instanciated. This is obviously a lot less efficient than
 13having specific implementations for each type, and for that reason AngelScript permits the
 14application to register a template specialization where the extra performance is needed. 
 15
 16This gives the best of both worlds, performance where the subtype is known before hand, and 
 17support for all other types that cannot be pre-determined.
 18
 19\section doc_adv_template_1 Registering the template type
 20
 21The template registration is registered similarly to normal \ref doc_reg_basicref "reference types",
 22with a few differences. The name of the type is formed by the name of the template type plus
 23the name of the subtype with angle brackets. The type flag asOBJ_TEMPLATE must also be used.
 24
 25\code
 26// Register the template type
 27r = engine->RegisterObjectType("myTemplate<class T>", 0, asOBJ_REF | asOBJ_GC | asOBJ_TEMPLATE); assert( r >= 0 );
 28\endcode
 29
 30The template type doesn't have to be \ref doc_gc_object "garbage collected", but since you may not know 
 31which subtypes it will be instanciated for, it is usually best to implement that support.
 32
 33When registering the behaviours, methods, and properties for the template type the type is identified
 34with the name and subtype within angle brackets, but without the class token, e.g. <tt>myTemplate&lt;T&gt;</tt>.
 35The sub type is identified by just the name of the subtype as it was declared in the call to RegisterObjectType.
 36
 37The factory behaviour for the template type is also different. In order for the implementation to know
 38which subtype it is instanciated for the factory receives the \ref asIObjectType of the template instance
 39as a hidden first parameter. When registering the factory this hidden parameter is reflected in the declaration,
 40for example as <tt>int &amp;in</tt>.
 41
 42\code
 43// Register the factory behaviour
 44r = engine->RegisterObjectBehaviour("myTemplate<T>", asBEHAVE_FACTORY, "myTemplate<T>@ f(int&in)", asFUNCTIONPR(myTemplateFactory, (asIObjectType*), myTemplate*), asCALL_CDECL); assert( r >= 0 );
 45\endcode
 46
 47Remember that since the subtype must be determined dynamically at runtime, it is not possible to declare
 48functions to receive the subtype by value, nor to return it by value. Instead you'll have to design the
 49methods and behaviours to take the type by reference. It is possible to use object handles, but then
 50the script engine won't be able to instanciate the template type for primitives and other values types.
 51
 52\see \ref doc_addon_array
 53
 54\section doc_adv_template_4 Validating template instantiations at compile time
 55
 56In order to avoid unnecessary runtime validations of invalid template instantiations, the application 
 57should preferably register the \ref asBEHAVE_TEMPLATE_CALLBACK behaviour. This is a special behaviour function
 58that the script engine will invoke everytime a new template instance type is generated. The callback
 59function can then perform necessary validations to verify if the type can be handled, and if not tell
 60the engine that the instance isn't supported. 
 61
 62The callback function must be a global function that receives an asIObjectType pointer, and should return 
 63a boolean. If the template instance is valid the return value should be true.
 64
 65\code
 66// Register the template callback
 67r = engine->RegisterObjectBehaviour("myTemplate<T>", asBEHAVE_TEMPLATE_CALLBACK, "bool f(int &in)", asFUNCTION(myTemplateCallback), asCALL_CDECL); assert( r >= 0 );
 68\endcode
 69
 70Here's an example callback function:
 71
 72\code
 73bool myTemplateCallback(asIObjectType *ot)
 74{
 75  // This template will only support primitive types
 76  int typeId = ot->GetSubTypeId();
 77  if( typeId & asTYPEID_MASK_OBJECT )
 78  {
 79    // The script is attempting to instantiate the 
 80    // template with an object type, this is not allowed.
 81    return false;
 82  }
 83    
 84  // Primitive types are allowed
 85  return true;
 86}
 87\endcode
 88
 89
 90
 91\section doc_adv_template_2 Template specializations
 92
 93When registering a template specialization you override the template instance that AngelScript would normally
 94do when compiling a declaration with the template type. This allow the application to register a completely
 95different object with its own implementation for template specializations. Obviously it is recommended that
 96the template specialization is registered so that to the script writer it is transparent, i.e. try to avoid
 97having different method names or behaviours for the template type and template specializations.
 98
 99With the exception of the type name, a template specialization is registered exactly like a \ref doc_register_type "normal type". 
100
101\code
102// Register a template specialization for the float subtype
103r = engine->RegisterObjectType("myTemplate<float>", 0, asOBJ_REF); assert( r >= 0 );
104  
105// Register the factory (there are no hidden parameters for specializations)
106r = engine->RegisterObjectBehaviour("myTemplate<float>", asBEHAVE_FACTORY, "myTemplate<float>@ f()", asFUNCTION(myTemplateFloatFactory, (), myTemplateFloat*), asCALL_CDECL); assert( r >= 0 );
107\endcode
108
109
110
111
112
113\section doc_adv_template_3 Current limitations
114
115 - Template types are currently limited to reference types only, i.e. it must be registered
116   with a factory and addref and release behaviours.
117   
118 - Only one template subtype can be used at the moment.
119 
120
121
122*/