写好开源项目的示例代码

当你的系统发布时，你需要告诉用户如何去使用，通常你会写一份示例代码放在文档中，让用户能通过这个例子快速知道该如何使用，这个实例代码对用户会有多大影响呢？

TFS是淘宝的分布式文件系统，主要用于小对象的存储（如图片、交易快照等），在TFS的开源wiki上，也有一个简单的实例。具体的说，TFS客户端提供了基本的open、read、write、close接口，用户在读写前，需要先根据对应的模式open一下，然后调用read或write进行读写，最后用户调用close关闭文件，这个过程与linux标准文件系统的过程是类似的。另外，TFS客户端还提供了一个fstat的接口用于获取文件的基本信息（如大小、创建时间等）。

 

TFS的读文件的示例代码是这么写的：

fd = tfsclient.open(filename, ...);
tfsclient.fstat(fd, &stat);                 // 在调用read前，先调用stat获取文件大小
tfsclient.read(fd, buf, stat.size);    // 不调用stat直接read也是可以的
tfsclient.close(fd);

最近，内核组的同时通过在线上抓取日志进行分析，发现约80%的read前对该文件调用了stat，可以看出示例代码深深的影响到了用户的使用方式，写好example是非常重要的。

针对上述现象，我们分析了stat、read对应的DS行为，并进行了优化：

1. 客户端一次stat对应DS的行为：读文件的index，根据index读取block对应位置的文件元数据（FileInfo结构）。
2. 客户端一次read对应DS的行为：读文件的index，根据index读取block对应位置文件的数据。
3. 在block上文件数据紧接着文件的FileInfo信息存储。

由于80%的read前都会有对应文件的stat调用，也就是说当读取到文件的FileInfo，很有可能马上就会用到紧跟其后的文件数据，如果在stat时对文件数据进行预读，接下来调用read时，就不需要再到磁盘上读取文件数据，从而节省一次磁盘IO；通过线下的模拟测试，发现上述预读优化的确是有作用的。