From 42167cd9063deef116feac0bc68b3693e2c8af63 Mon Sep 17 00:00:00 2001 From: Xenni_cp Date: Wed, 6 May 2009 01:05:39 +0000 Subject: [PATCH] Added comments to DynamicMethodEmit compiler-time service I wrote. Should be alot easier to use now! --- source/Indy.IL2CPU/DynamicMethodEmit.cs | 106 +++++++++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-) diff --git a/source/Indy.IL2CPU/DynamicMethodEmit.cs b/source/Indy.IL2CPU/DynamicMethodEmit.cs index 99cd6d588..53cd03ee6 100644 --- a/source/Indy.IL2CPU/DynamicMethodEmit.cs +++ b/source/Indy.IL2CPU/DynamicMethodEmit.cs @@ -6,19 +6,63 @@ using System.Collections.Generic; namespace Indy.IL2CPU { + /// + /// Provides Compile-Time Service which enables the emission of dynamic methods. + /// + /// + /// If a method has a variable number (or type) of parameters which depend on its context, + /// this feature can be used to improve code-reuse and optimize performance. + /// + /// + /// To create a dynamic method emitter, one must create two classes derived from: + /// CEmittedMethodInfo + /// CMethodEmitterInfo + /// And register the CMethodEmitterInfo in the DynamicMethodEmit constructior. + /// public class DynamicMethodEmit { + /// + /// Provides information about an emitted method, including the ability to find if + /// that particular emitted method overides another method. + /// public abstract class CEmittedMethodInfo { + /// + /// Returns true if the emitted method can override the provided method. + /// + /// The method to check overridability for. + /// True, if this method is suitable, otherwise, false. public abstract bool GetHandlesMethod(MethodBase method); + /// + /// Gets the MethodInfo of the emitted method which can overide the provided method. + /// + /// The method to retrieve an overide for. + /// The MethodInfo of the emitted method which can overide the provided method. public abstract MethodInfo GetHandlerForMethod(MethodBase method); } + /// + /// Provides information about a method emitter, including the ability to find if that + /// particular method emitter can emit a method overides another method. + /// public abstract class CMethodEmitterInfo { + /// + /// Returns true if this emitter can emit a method which overides the provided method. + /// + /// The method to check overrideability of. + /// True, if this emitter can emit a method which overides the provided method, otherwise, false. public abstract bool GetEmittsMethod(MethodBase method); + /// + /// Emitts a method which can overide the provided method. + /// + /// The method to overide. + /// The MethodInfo of the emitted method which can override the provided method. public abstract MethodInfo EmitMethod(MethodBase method); } + /// + /// CEmittedMethodInfo for Multidimensional Arrays + /// public class MAMGroup : CEmittedMethodInfo { public Type arrayType; @@ -60,6 +104,9 @@ namespace Indy.IL2CPU } } } + /// + /// CMethodEmitterInfo for Multidimensional Arrays + /// public class MAMEmitter : CMethodEmitterInfo { private static void EmitRecursiveFillArray(int ranknum, int maxranks, Type arrayType, ILGenerator EmitIL) @@ -203,15 +250,49 @@ namespace Indy.IL2CPU } } + /// + /// Operating instance of the DynamicMethodEmit class. + /// public static DynamicMethodEmit Instance = new DynamicMethodEmit(AppDomain.CurrentDomain); + /// + /// AppDomain into which emission is occuring. + /// public readonly AppDomain EmitDomain; + /// + /// Assembly into which emission is occuring. + /// public readonly AssemblyBuilder EmitAssm; + /// + /// Module into which emission is occuring. + /// public readonly ModuleBuilder EmitModu; + + /// + /// Container Type of the methods which are currently being emitted. + /// public TypeBuilder EmitContType; + /// + /// Number of Emitted menthods in the current Container Type. + /// private int EmitCount = 0; + /// + /// Current number of Container Types. + /// private int TypeCount = 0; + /// + /// List of all the currently emitted methods. + /// + /// + /// If a CEmittedMethodInfo is to be used, it must be present in this list. + /// List CEMIs = new List(); + /// + /// List of all the method emitters. + /// + /// + /// If a CMethodEmitterInfo is to be used, it must be present in this list. + /// List CMEIs = new List(); public DynamicMethodEmit(AppDomain aEmitDomain) @@ -220,11 +301,17 @@ namespace Indy.IL2CPU EmitAssm = EmitDomain.DefineDynamicAssembly(new AssemblyName() { Name = "IndyIL2CPU_EmitAssm" }, AssemblyBuilderAccess.RunAndSave); EmitModu = EmitAssm.DefineDynamicModule("IndyIL2CPU_EmitAssm"); - CMEIs.Add(new MAMEmitter()); + //Register CMethodEmitterInfos Here + CMEIs.Add(new MAMEmitter()); //Multidimensional Arrays Instance = this; } + /// + /// Begins a type to which emission will occur. + /// After all desired methods have been emitted, + /// call EndType() to get the MethodInfos. + /// public static void BeginType() { Instance.EmitContType = Instance.EmitModu.DefineType( @@ -233,6 +320,10 @@ namespace Indy.IL2CPU ); Instance.EmitCount = 0; } + /// + /// Finializes emission of a type. + /// + /// MethodInfos of the emitted methods. public static MethodInfo[] EndType() { Type t = Instance.EmitContType.CreateType(); @@ -244,6 +335,10 @@ namespace Indy.IL2CPU return mbs; } + /// + /// Returns true if DynamicMethodEmit Instance currently contains an emitter which can overide the provided Method. + /// The method to search for an overide emitter for. + /// True if a suitable emitter was found, otherwise, false. public static bool GetHasDynamicMethod(MethodBase method) { foreach (CMethodEmitterInfo cmei in Instance.CMEIs) @@ -254,6 +349,15 @@ namespace Indy.IL2CPU return false; } + /// + /// Returns the MethodInfo of the method which can overide the provided method, + /// generating it if nessecary. + /// + /// The method to overide. + /// The MethodInfo of the suitable override. + /// + /// Thrown if a sutiable override could not be found or generated. + /// public static MethodInfo GetDynamicMethod(MethodBase method) { foreach (CEmittedMethodInfo cemi in Instance.CEMIs)