Agent库（SPADES v0.7的一部分）用户指导和参考手册

Agent库（SPADES v0.7的一部分）用户指导和参考手册

Patrick Riley pfr+@cs.cmu.edu

2003.5.27

翻译：许元xychn15@yahoo.com.cn

 

1. 绪论

这是一篇关于Agent库（SPADES的一部分）的文档。这篇文档没有覆盖SPADES的所有功能，这些在其他的文档中可以找到。

Agent库提供C++接口使agent和server交互。Agent库支持以正确的格式传送信息。Agent库使用了SPADES库中的一些类，并有四个主要的新增类（还有一些子类）：

AgentCommInterface 这个类是接口的主要点。所有传送的信息都通过这个类。

ToCSMessage 这是一个虚基类。子类提供各种发送给server的信息。

FromCSMessage 这是一个虚基类。子类提供各种从server接收的信息。

AgentLibraryParam 这是ParamReader(在SPADES主文档中描述)的子类，类ParamReader包含了控制Agent库的参数。

 

Agent库还提供了动作和错误log工具，这在SPADES主文档中都有描述。

 

2.AgentCommInterface

这个类是接口的主要点。它支持发送信息。

函数有：

Constructor

根据参数input_fd和ooutput_fd设置读写文件，但并不发送任何信息。

 

Destructor

关闭与server通讯的通道。

 

tryMessageRead

试图从server读取信息并返回信息。这个函数不会阻塞，没有信息就返回NULL。

 

receiveMessage

像tryMessageRead一样，除了可能阻塞,以num_select_timeouts为最大次数等待信息，每次等待指定参数wait_sec和wait_usec。如果超时或者接收的信息有错误就返回NULL(并设置关闭标志)。

 

shouldShutdown

返回关闭标志是否设置，initiateShutdown、输入通道错误和超时都会设置关闭标志。

 

initiateShutdown

设置关闭标志为true。

 

getLatestTime

返回最近接收信息的时间。

send

发送信息（ToCSMessage的一个类型）

 

getOutstandingThinks

得到是否完成思考。除非出错，否则就是1或0。换句话说，如果agent正在思考周期，就返回1，否则返回0。

 

3.ToCSMessage

这是一个虚基类，可以从agent向server发送信息。

Print

使用操作符<<打印信息。这主要用在调试和有目的的信息上。

 

getOutstandingThinkMod

返回这条信息影响思考之外的数字（完成思考-1，感觉+1，等）。

 

writeTo

按照SPADES server通讯标准写信息。

 

ToCSMessage有一个子类，agent可以用它来向server发送信息。这些类使用了DataArray，DataArry在SPADES主文档中描述。

ToCSMessage_Act

使用DataArray作为参数处理要发送的字符。

 

ToCSMessage_RequestTimeNotify 

将一个整数转化为要求时间通报的时间。

 

ToCSMessage_MigrationData

使用DataArray作为参数处理agent新的数据。

 

ToCSMessage_DoneThinking

完成思考信息告诉server这个agent已经完成思考周期。

 

ToCSMessage_Exit

向server通报agent退出。

 

ToCSMessage_InitDone

向server通报agent初始化完成。

 

4.FromCSMessage

这是一个虚基类，agent可以从server接收信息。

这个类的函数有：

Print

使用操作符<<打印信息。这主要用在调试和有目的的信息上。

 

getOutstandingThinkMod

返回这条信息影响思考之外的数字（完成思考-1，感觉+1，等）。

 

accept

为了避免使用者计算时间类型或者其他痛苦的东西，这个类按照来宾模式设计。为了分别处理不同的消息，你可以使用子类FromCSMessage::Visitor或者FromCSMessage::ConstVisitor。FromCSMessage的这些子类都有访问函数。当你有一条要处理的信息，你可以用FromCSMessage::Visitor或者FromCSMessage::ConstVisitor调用accept函数处理。您的对象将调用适当的访问函数。

 

FromCSMessage有一个子类，agent可以用它来接收server发送的信息。这些类使用了DataArray，DataArry在SPADES主文档中描述。FromCSMessage的子类有：

 

FromCSMessage_InitData

启动之后，发送的初始化数据。如果不是移动的数据将是空的。

 

FromCSMessage_Exit

要求agent退出。将不再发送或接收信息。

 

FromCSMessage_Sense

这是一个感觉信息。这有可能是也有可能不是思考周期（可以使用getThinking函数得到）。你可以获取与感觉相关信息数据和时间。

 

FromCSMessage_TimeNotify

每个要求时间通报之后发送一个时间通报。这有可能是也有可能不是思考周期（可以使用getThinking函数得到）。

 

FromCSMessage_MigrationRequest

要求agent发回一个移动数据信息，因为即将移动。

 

FromCSMessage_Error

server的一个错误。错误被作为一个字符串存储。可能值和其意义在SPADES主文档中描述。

 

FromCSMessage_ThinkTime

通报agent上次思考周期使用的时间。

 

5.参数

类AgentLibraryParam包含下列参数。还提供了分析命令行中的和文件中的参数的工具，这同在SPADES主文档中描述的类ParamReader一样。

你可以继承类AgentLibraryParam来添加你自己的参数。

 

 

 

名称	类型	描述	默认
logfile_dir	String	log文件的输出目录	Logfiles
action_log_fn	String	动作log的文件名(用于调试信息) 见SPADES主文档的详细描述	actions.log
action_log_level	Integer	输出动作log的最高等级。 见SPADES主文档的详细描述	0
random_seed	Integer	随机生成数值。 任何负值将导致从/dev/urandom中读取	-1
wait_sec	Integer(>=0)	receiveMessage中的选择等待时间(秒)	5
wait_usec	Integer(>=0)	receiveMessage中的选择等待时间(微秒)?	0
num_selects_timeout	Integer(>=0)	在agent退出之前，允许没有接收信息的时间	20
input_fd	Integer(>=3)	从server接收信息的描述文件。 这必须与agent的类型数据库吻合。	3
output_fd	Integer(>=3)	发送给server的信息的描述文件。 这必须与agent的类型数据库吻合。	4

 

6.实例

例子agent给出了一个使用Agent库的完整例子。这个部分提供了一些编程之前你可能要做的步骤。

 

Allocate a parameter object(subclass of AgentLibraryParam)

Call getOptions on that object

Logger::instance()->setTagFunction(new AgentTagFunction);

Logger::instance()->setMaxActionLogLevel(AgentLibraryParam::instance()->getActionLogLevel());

spades::seedRandom(AgentLibraryParam::instance()->getRandomSeed());

Allocate pacsi,of type AgentCommInterface

FromCSMessage* m;

while((m=pasci->receiveMessage())!=NULL)

       Process message m

       deletem;