Home - sourcemod-central - file revision - sourcepawn/include/sp_vm_api.h@b00ab8fec541 Mercurial
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
sourcepawn/include/sp_vm_api.h
author David Anderson <dvander@alliedmods.net>
Sun Sep 24 06:17:10 2006 +0000 (2006-09-24)
changeset 93 b00ab8fec541
parent 69 e23e2b0a2d7e
child 149 6950d56d82d1
permissions -rw-r--r--
reorganized ungen opcode stuff
fixed mislabeled ungen ops, then added appropriate notes
added executable memory functions to API
compilation results in an sp_context_t, not a BaseContext now
renamed FreeContextVars() to FreeContext()
other minor changes 
     1 #ifndef _INCLUDE_SOURCEPAWN_VM_API_H_
     2 #define _INCLUDE_SOURCEPAWN_VM_API_H_
     3 
     4 #include <stdio.h>
     5 #include "sp_vm_types.h"
     6 #include "sp_vm_context.h"
     7 
     8 namespace SourcePawn
     9 {
    10 	class IPluginContext;
    11 
    12 	/**
    13 	 * Contains helper functions used by VMs and the host app
    14 	 */
    15 	class ISourcePawnEngine
    16 	{
    17 	public:
    18 		/**
    19 		* Loads a named file from a file pointer.  
    20 		* Using this means base memory will be allocated by the VM.
    21 		* 
    22 		* @param fp		File pointer.  May be at any offset.  Not closed on return.
    23 		* @param err		Optional error code pointer.
    24 		* @return			A new plugin structure.
    25 		*/	
    26 		virtual sp_plugin_t *LoadFromFilePointer(FILE *fp, int *err) =0;
    27 	
    28 		/**
    29 		 * Loads a file from a base memory address.
    30 		 *	
    31 		 * @param base		Base address of the plugin's memory region.
    32 		 * @param plugin	If NULL, a new plugin pointer is returned.
    33 		 *                  Otherwise, the passed pointer is used.
    34 		 * @param err		Optional error code pointer.
    35 		 * @return			The resulting plugin pointer.
    36 		 */
    37 		virtual sp_plugin_t *LoadFromMemory(void *base, sp_plugin_t *plugin, int *err) =0;
    38 
    39 		/**
    40 		 * Frees all of the memory associated with a plugin file.
    41 		 * If allocated using SP_LoadFromMemory, the base and plugin pointer 
    42 		 *  itself are not freed (so this may end up doing nothing).
    43 		 */
    44 		virtual int FreeFromMemory(sp_plugin_t *plugin) =0;
    45 
    46 		/**
    47 		 * Creates a new IContext from a context handle.
    48 		 *
    49 		 * @param ctx		Context to use as a basis for the IPluginContext.
    50 		 * @return			New IPluginContext handle.
    51 		 */
    52 		virtual IPluginContext *CreateBaseContext(sp_context_t *ctx) =0;
    53 
    54 		/** 
    55 		 * Frees a context.
    56 		 *
    57 		 * @param ctx		Context pointer to free.
    58 		 */
    59 		virtual void FreeBaseContext(IPluginContext *ctx) =0;
    60 
    61 		/**
    62 		 * Allocates large blocks of temporary memory.
    63 		 * 
    64 		 * @param size		Size of memory to allocate.
    65 		 * @return			Pointer to memory, NULL if allocation failed.
    66 		 */
    67 		virtual void *BaseAlloc(size_t size) =0;
    68 
    69 		/**
    70 		 * Frees memory allocated with BaseAlloc.
    71 		 *
    72 		 * @param mem		Memory address to free.
    73 		 */
    74 		virtual void BaseFree(void *memory) =0;
    75 
    76 		/**
    77 		 * Allocates executable memory.
    78 		 *
    79 		 * @param size		Size of memory to allocate.
    80 		 * @return			Pointer to memory, NULL if allocation failed.
    81 		 */
    82 		virtual void *ExecAlloc(size_t size) =0;
    83 
    84 		/**
    85 		 * Frees executable memory.
    86 		 *
    87 		 * @param mem		Address to free.
    88 		 */
    89 		virtual void ExecFree(void *address) =0;
    90 	};
    91 
    92 	class ICompilation
    93 	{
    94 	public:
    95 		virtual ~ICompilation() { };
    96 	};
    97 
    98 	class IVirtualMachine
    99 	{
   100 	public:
   101 		/**
   102 		 * Returns the string name of a VM implementation.
   103 		 */
   104 		virtual const char *GetVMName() =0;
   105 
   106 		/**
   107 		 * Begins a new compilation
   108 		 * 
   109 		 * @param plugin	Pointer to a plugin structure.
   110 		 * @return			New compilation pointer.
   111 		 */
   112 		virtual ICompilation *StartCompilation(sp_plugin_t *plugin) =0;
   113 
   114 		/**
   115 		 * Sets a compilation option.
   116 		 *
   117 		 * @param co		Pointer to a compilation.
   118 		 * @param key		Option key name.
   119 		 * @param val		Option value string.
   120 		 * @return			True if option could be set, false otherwise.
   121 		 */
   122 		virtual bool SetCompilationOption(ICompilation *co, const char *key, const char *val) =0;
   123 
   124 		/**
   125 		 * Finalizes a compilation into a new sp_context_t.
   126 		 * Note: This will free the ICompilation pointer.
   127 		 *
   128 		 * @param co		Compilation pointer.
   129 		 * @param err		Filled with error code on exit.
   130 		 * @return			New plugin context.
   131 		 */
   132 		virtual sp_context_t *CompileToContext(ICompilation *co, int *err) =0;
   133 
   134 		/**
   135 		 * Aborts a compilation and frees the ICompilation pointer.
   136 		 *
   137 		 * @param co		Compilation pointer.
   138 		 */
   139 		virtual void AbortCompilation(ICompilation *co) =0;
   140 
   141 		/**
   142 		 * Frees any internal variable usage on a context.
   143 		 *
   144 		 * @param ctx		Context structure pointer.
   145 		 */
   146 		virtual void FreeContext(sp_context_t *ctx) =0;
   147 
   148 		/**
   149 		 * Calls the "execute" function on a context.
   150 		 *
   151 		 * @param ctx		Executes a function in a context.
   152 		 * @param code_idx	Index into the code section.
   153 		 * @param result	Pointer to store result in.
   154 		 * @return			Error code (if any).
   155 		 */
   156 		virtual int ContextExecute(sp_context_t *ctx, uint32_t code_idx, cell_t *result) =0;
   157 	};
   158 };
   159 
   160 #endif //_INCLUDE_SOURCEPAWN_VM_API_H_
sourcemod-central
Feed