[NAME]
ALL.daovm.interface.embedding

[TITLE]
嵌入道虚拟机

[DESCRIPTION]


 1   一个简单的例子     
 1   一个简单的例子     
 1   一个简单的例子     

 1.1   初始化道运行环境  

在使用道库做任何事之前,DaoInit()必须被调用以初始化道运行环境。
     
   1  // 初始化道:
   2  DaoVmSpace *vmspace = DaoInit( NULL );
     
这个函数将返回一DaoVmSpace对象,该对象可用来载入道脚本或模块。 此函数可以接受一char*字符串参
数,传入的此参数应当是此程序的路径 和名称,用来确定额外的模块搜寻路径。

 1.2   载入脚本文件  

一旦你有了一个DaoVmSpace对象,你可以开始运行道脚本或载入道模块了。 如果你有一个主脚本文件,并
且你所要做的仅仅是执行这个文件,你可以简单地调用: 
     
   1  // 载入并执行 "myscript.dao":
   2  DaoVmSpace_Load( vmspace, "myscript.dao" );
     
顶层作用域的代码将被执行。
 1.3   退出道环境  

在你用完道虚拟机后,你可以调用以下函数来正确地终止道虚拟机并退出道环境。 调用这个这个函数将
会等待未完成的线程结束,也会等待垃圾回收器回收完垃圾对象, 并且释放一些内部数据结构等。 
     
   1  // 退出 Dao:
   2  DaoQuit();
     

 1.4   将这些代码放在一起  

将这些代码放在一起,嵌入道就如下面的例子简单: 
     
   1  // 初始化 Dao:
   2  DaoVmSpace *vmspace = DaoInit( NULL );
   3  // 载入运行 "myscript.dao":
   4  DaoVmSpace_Load( vmspace, "myscript.dao" );
   5  // 退出 Dao:
   6  DaoQuit();
     


 2   一个稍微高级点的例子     
 2   一个稍微高级点的例子     
 2   一个稍微高级点的例子     

在道里,每个代码文件在编译后都会被表示为一个命名空间对象, 它存有这个文件里的和一些它载入的
文件里的全局常量和变量等。 要做任何实际的事情,你一般都要用到这个命名空间对象。

 2.1   获得命名空间对象  

接着上面的例子,如果你想要调用"myscript.dao"里的某个函数, 你可以先保存DaoVmSpace_Load()所返
回的命名空间对象: 
     
   1  // 载入 "myscript.dao" 并获得命名空间对象:
   2  DaoNamespace *nspace = DaoVmSpace_Load( vmspace, "myscript.dao" );
     


 2.2   获取函数对象  

要找到你想调用的函数,使用如下代码: 
     
   1  // 查找名为 "myfunction" 的对象:
   2  DaoValue *value = DaoNamespace_FindData( nspace, "myfunction" );
   3  // 尝试将它转换为函数对象:
   4  DaoRoutine *myfunc = DaoValue_CastRoutine( value );
     
如果"myfunction"确实是个函数对象,myfunc将不会是空指针。

 2.3   获得虚拟机进程对象  

道程序都是以虚拟机进程的方式在道虚拟机上运行。 因此若要调用前面的函数,你将需要一个虚拟机进
程对象DaoProcess。 这种对象可由直接调用DaoProcess_New()生成, 但是更好的方式是从DaoVmSpace对
象获得, 这种方式更经济,更方便管理。 
     
   1  // 获得虚拟机进程对象:
   2  DaoProcess *proc = DaoVmSpace_AcquireProcess( vmspace );
     

 2.4   准备参数值  

现在假定函数"myfunction"需要一个整数作为第一个参数和一个字符串作为第二个参数。 为了调用它,
我们将需要先准备好一个道整数对象和一个道字符串对象。 这些对象都可通过它们相应的分配器函数生
,但是更好的方式则是使用 DaoProcess类型的“工厂”方法产生。 这些方法一般以DaoProcess_New开头。
例如,生成道整数对象和道字符串对象,我们可以用: 
     
   1  // 准备道整数对象和道字符串对象:
   2  DaoInteger *ivalue = DaoProcess_NewInteger( proc, 123 );
   3  DaoString  *svalue = DaoProcess_NewString( proc, "abc", -1 );
     
The third parameter of  DaoProcess_NewString()的第三个参数是前面C字符串的长度, 如果为负值
,该字符串是以NULL作为结束标识。

这些对象必须放在数组里才能传递给"myfunction"函数: 
     
   1  DaoValue *params[2];
   2  params[0] = (DaoValue*) ivalue;
   3  params[1] = (DaoValue*) svalue;
     
因为这些对象是有DaoProcess的方法生成的, 你也可以通过下面的以数组得方式获得这些对象: 
     
   1  // 获取最后产生的两个对象:
   2  DaoValue **params = DaoProcess_GetLastValues( proc, 2 );
     


 2.5   调用道函数  

现在我们已经可以用准备好的参数调用前面获得的函数了: 
     
   1  // 调用函数:
   2  DaoProcess_Call( proc, myfunc, NULL, params, 2 );
     
对于类方法,一个类实例对象可作为该函数的第三个参数传入。 不过它也可作为params数组的第一个元
素传入。 值得注意的是这个函数能处理重载过的函数,因此你不需要为此做任何事 (当然还是要传入正
的参数对象)。 没有错误的情况下,这个函数将返回零,否则返回一个表示错误的整数。

 2.6   获得函数的返回值  

如果上面的函数有返回值,该返回值可通过下面的函数获得: 
     
   1  // 获得函数的返回值:
   2  DaoValue *retvalue = DaoProcess_GetReturned( proc );
     
如果函数只返回某个特定类型的值,那么你可用DaoValue_CastXXX() 之类的函数将获得的值转换到该类
型。 你也可以使用DaoValue_TryGetXXX()将它直接转换到相应的C类型。 例如,如果"myfunction"返回整
数,你可通过下面的方式获得。 
     
   1  // 获得返回的整数:
   2  daoint retint = DaoValue_TryGetInteger( retvalue );
     

 2.7   释放虚拟进程对象  

当你使用完一个虚拟进程对象后,你需要释放它。 最好的方式是将它是放回DaoVmSpace对象,以便重用。
     
   1  // 释放虚拟进程对象:
   2  DaoVmSpace_ReleaseProcess( vmspace, proc );
     
但如果你需要频繁地使用一个虚拟进程对象, 你可以保留它直到最后不需要的时候。 不过这样的话,就
有必要释放前面准备的参数了: 
     
   1  // 释放缓存的参数:
   2  DaoProcess_PopValues( proc, 2 );
     


 2.8   将这些代码放在一起  

     
   1  // 载入 "myscript.dao" 并获得命名空间对象:
   2  DaoNamespace *nspace = DaoVmSpace_Load( vmspace, "myscript.dao" );
   3  // 查找名为 "myfunction"的对象:
   4  DaoValue *value = DaoNamespace_FindData( nspace, "myfunction" );
   5  // 尝试转换为函数对象:
   6  DaoRoutine *myfunc = DaoValue_CastRoutine( value );
   7  
   8  // 获得进程对象:
   9  DaoProcess *proc = DaoVmSpace_AcquireProcess( vmspace );
  10  
  11  // 准备一个整数对象和字符串对象:
  12  DaoInteger *ivalue = DaoProcess_NewInteger( proc, 123 );
  13  DaoString  *svalue = DaoProcess_NewString( proc, "abc", -1 );
  14  // 以数组的形式获得这两个对象:
  15  DaoValue **params = DaoProcess_GetLastValues( proc, 2 );
  16  
  17  // 调用函数:
  18  DaoProcess_Call( proc, myfunc, NULL, params, 2 );
  19  
  20  // 获取函数的返回值:
  21  DaoValue *retvalue = DaoProcess_GetReturned( proc );
  22  // 获取返回的整数值:
  23  daoint retint = DaoValue_TryGetInteger( retvalue );
  24  
  25  // 释放进程对象:
  26  DaoVmSpace_ReleaseProcess( vmspace, proc );