[NAME]
ALL.daovm.interface.embedding

[TITLE]
Embedding Dao VM

[DESCRIPTION]


 1   A Simple Example     
 1   A Simple Example     
 1   A Simple Example     

 1.1   Initializing Dao Runtime  

Before doing anything with Dao as a library, one must call DaoInit() to initialize it fir
st:
     
   1  // Initialize Dao:
   2  DaoVmSpace *vmspace = DaoInit( NULL );
     
This function will return a DaoVmSpace object, which can be used to load Dao scripts or m
odules. It can optionally take a char* parameter, which is assumed to be the path and nam
e of the application, and is used to add additional searching paths.

 1.2   Load A Script File  

Once you have a DaoVmSpace object, you can start to run Dao scripts or load Dao modules u
sing this object. If you have a main script file and all you need to do is to run the fil
e, you can simply call:
     
   1  // Load and execute "myscript.dao":
   2  DaoVmSpace_Load( vmspace, "myscript.dao" );
     

 1.3   Finalize Dao Runtime  

After you are done with Dao, you may call the following function to make sure, Dao is pro
perly finalized (waiting for unjoined threads to finish and the garbage collector to fini
sh, and deallocating some internal data structures etc.). 
     
   1  // Finalize (or Quit) Dao:
   2  DaoQuit();
     

 1.4   Putting These Codes Together  

Putting these codes together, embedding Dao can be as simple as, 
     
   1  // Initialize Dao:
   2  DaoVmSpace *vmspace = DaoInit( NULL );
   3  // Load "myscript.dao":
   4  DaoVmSpace_Load( vmspace, "myscript.dao" );
   5  // Finalize (or Quit) Dao:
   6  DaoQuit();
     


 2   A Slightly More Advanced Example     
 2   A Slightly More Advanced Example     
 2   A Slightly More Advanced Example     

In Dao, each single script file is represented by one namespace object. And each namespac
e object has access to the public global constants and  variables defined in the files th
at this file has loaded. To do anything interesting, one must obtain the namespace object
for the file of interest.

 2.1   Obtaining The Namespace Object  

Following the above example, if you want to call a function defined in "myscript.dao" (or
in the files it has loaded), you can simple store the returned namespace object in a vari
able, 
     
   1  // Load "myscript.dao" and obtain the namespace object:
   2  DaoNamespace *nspace = DaoVmSpace_Load( vmspace, "myscript.dao" );
     


 2.2   Obtaining The Function Object  

To find the function you want to call, 
     
   1  // Find an object named "myfunction":
   2  DaoValue *value = DaoNamespace_FindData( nspace, "myfunction" );
   3  // Try to cast it to a function object:
   4  DaoRoutine *myfunc = DaoValue_CastRoutine( value );
     
If "myfunction" is indeed a function, myfunc will not be NULL.

 2.3   Obtaining A Process Object  

Now to call the function, you will need another type of object: DaoProcess, which represe
nts a virtual machine process and is responsible for executing scripts. You can directly 
call DaoProcess_New() to create a new process object, but normally the better to get a pr
ocess object is to acquire it from a DaoVmSpace object: 
     
   1  // Acquire a process object:
   2  DaoProcess *proc = DaoVmSpace_AcquireProcess( vmspace );
     

 2.4   Prepare Parameter Values  

Now suppose the function "myfunction" needs to take an integer as its first parameter and
a string as the second. To call it, we will need to prepare parameters that can be passed
to this function. The simplest way to do this is to use the data "factory" methods that a
re associated with the process type DaoProcess. Such methods are normally begin with 
DaoProcess_New. For example, to prepare an integer value and a string value, one can do,
     
   1  // Prepare an integer and a string:
   2  DaoInteger *ivalue = DaoProcess_NewInteger( proc, 123 );
   3  DaoString  *svalue = DaoProcess_NewString( proc, "abc", -1 );
     
The third parameter of DaoProcess_NewString() is the number of bytes in the C string, and
a negative value can be used to indicate the C string is NULL terminated.

To use these two new values in the parameter list to call "myfunction", you can do, 
     
   1  DaoValue *params[2];
   2  params[0] = (DaoValue*) ivalue;
   3  params[1] = (DaoValue*) svalue;
     
Or you can simply do,
     
   1  // Get the last two values:
   2  DaoValue **params = DaoProcess_GetLastValues( proc, 2 );
     
which will return last created two values in an array.

 2.5   Call The Function  

Now we are ready to call the function we obtained before with the prepared values, 
     
   1  // Call the function:
   2  DaoProcess_Call( proc, myfunc, NULL, params, 2 );
     
For class methods, a class instance object can be passed to this function as the third pa
rameter, or it can be passed as the first value of  params. Please note that, this functi
on can handle overloaded functions automatically! So you do not need to do anything for t
hat. This function will return zero on success, or other values with errors.

 2.6   Retrieve The Returned Value  

If the function returns a value, you can obtain it by, 
     
   1  // Obtain the returned value:
   2  DaoValue *retvalue = DaoProcess_GetReturned( proc );
     
If the returned value is supposed to be of certain type, you can cast it to that type by 
using one of the  DaoValue_CastXXX() functions, or directly convert it to a proper C type
by using one of the DaoValue_TryGetXXX() functions. For example, if "myfunction" returns 
an integer, you can get it by, 
     
   1  // Get the integer return value
   2  daoint retint = DaoValue_TryGetInteger( retvalue );
     

 2.7   Release The Process Object  

After you have done with the process object, you can release it back the DaoVmSpace objec
t, 
     
   1  // Release the process:
   2  DaoVmSpace_ReleaseProcess( vmspace, proc );
     
But if you want to use a process object frequently, you may simply retain it until you no
longer need it. Then you may also need to the follow function to release the cached value
s 
     
   1  // Pop the cached values:
   2  DaoProcess_PopValues( proc, 2 );
     


 2.8   Putting These Codes Together  

     
   1  // Load "myscript.dao" and obtain the namespace object:
   2  DaoNamespace *nspace = DaoVmSpace_Load( vmspace, "myscript.dao" );
   3  // Find an object named "myfunction":
   4  DaoValue *value = DaoNamespace_FindData( nspace, "myfunction" );
   5  // Try to cast it to a function object:
   6  DaoRoutine *myfunc = DaoValue_CastRoutine( value );
   7  
   8  // Acquire a process object:
   9  DaoProcess *proc = DaoVmSpace_AcquireProcess( vmspace );
  10  
  11  // Prepare an integer and a string:
  12  DaoInteger *ivalue = DaoProcess_NewInteger( proc, 123 );
  13  DaoString  *svalue = DaoProcess_NewString( proc, "abc", -1 );
  14  // Get the last two values:
  15  DaoValue **params = DaoProcess_GetLastValues( proc, 2 );
  16  
  17  // Call the function:
  18  DaoProcess_Call( proc, myfunc, NULL, params, 2 );
  19  
  20  // Obtain the returned value:
  21  DaoValue *retvalue = DaoProcess_GetReturned( proc );
  22  // Get the integer return value
  23  daoint retint = DaoValue_TryGetInteger( retvalue );
  24  
  25  // Release the process:
  26  DaoVmSpace_ReleaseProcess( vmspace, proc );