kiwi简介

1. 概述
   我的整个跨平台研发工作暂命名为kiwi。这个工作产生的工作成果直接构成了kiwi。
   kiwi是什么？
   Kiwi是一个跨平台应用程序开发、运行框架。这点有别于hotfox。Hotfox定位于应用服务器开发、运行框架。Kiwi将应用服务器框架作为一个子项目在kiwi框架中做为一个可选项。
   Kiwi不同于QT。QT是一个应用程序开发库。这里我想用通俗的比喻阐释库与框架的区别。库就像是一堆零部件，你可以使用这些零部件来拼装一辆卡车或一台电脑。而框架则像是一个毛胚房，需要做的是局部的装饰。
   Kiwi也是一个开发库（其本身就是基于库研发出来的（libkiwi）），基于libkiwi，可以避免从头开始，从零部件开始。
   Kiwi还有以下几个新特性：
    跨平台，支持windows和linux
    采用unicode编码，支持国际化与本地化
    支持64位操作系统
    支持面向插件开发，灵活，复用程度高
    内置日志模块，提供多种等级日志，同时支持输出到屏幕和日志文件，可设置单个日志文件最大大小限制，超过限制自动拆分文件。
    支持windows服务运行方式，支持安装、卸载、启停服务的命令行操作模式

2. kiwi遵守的编码规范
   2.1. 命名规范
   源码文件名：小写字母，单词间用”_”(下划线）分隔，例如：thread_pool。
   接口名：以大写字母I开头，后续单词首字母大写，例如：IThreadPool。
   类名：各单词首字母大写，例如：ThreadPool。
   成员变量名：小写字母，单词间用”“(下划线）分隔，名称末尾加以”“(下划线）结束，例如：int thread_count_;
   局部变量：小写字母，单词间用”_”(下划线）分隔，例如：int thread_count;
   工程名：小写字母，单词间用”_”(下划线）分隔，例如：thread_pool。
   插件二进制名：为工程名加上.pin（动态库win32为.dll，linux为.so，名称平台不一致，因此改为平台一致的别名）
   名称空间名：小写字母，单词间用”_”(下划线）分隔，例如：name space util{};
   内联函数文件名：扩展名为.ipp

注：
单词若过长（通常超过10个字符），则可以考虑采用缩写，缩写后单词字母数要保持在5个字符以内，例如：international，缩写为i18n。

2.2. 名称空间规范
顶级名称空间为kiwi,其下按照类型划分子空间，如kiwi::db,kiwi::network,kiwi::util,kiwi::plugin等。

插件名称空间：插件名字空间在kiwi::plugin下，以插件自身名字命名，例如。
name space kiwi::plugin::rsswap{};

2.3. 注释规范
采用Doxygen兼容的JavaDoc规范。

块注释
/**
* …注释块…
*/

注释块前的*可选。

单行注释
///
/// …注释…
///

模块注释
定义模块（组）
/*
* @defgroup 模块名（具有唯一性） 模块的说明文字
* @{
*/
… 定义的内容 …
/* @} / // 模块结

增加到组中
在文档块中增加:ingroup 模块名

文件注释
/**
* @file test.cpp
* @author [e-mail]
* @version 0.1
* @date 2012-12
* @defgroup testgroup test
* @ingroup base 文件所在组
* @brief 日期处理类 .
* @details 对日期包装的处理
*
* @history
*/

类注释
/**
* @class CTest
* @ingroup testgroup
* @brief test class
* @details test details class
*/
class CTest{ };

函数注释
/**
* a normal member taking two arguments and returning an integer value.
* @param[in] a an integer argument.
* @param[out] s a constant character pointer.
* @see testMe2()
* @return The test results
*/

变量注释
/**
* test var
*/
double test;
或
double test; ///< test var
或
double test; /*< test var /

1. 目录结构
   

注意一个原则：

src目录下存放的是存源码，任何编译输出文件都不应该指向该目录及其下级目录。

1. 开发环境配置
   4.1. 下载源码
   从svn://192.168.0.121/kiwi/下载到本地。
   4.2. 统一路径
   共享/kiwi/trunk目录，并创建trunk共享目录的映射盘W盘。
   共享/kiwi/vendor，并创建vendor共享目录的映射盘V盘。
   注意：开发人员统一将第三方库的路径虚拟为V:,kiwi路径为w:。
   4.3. vs2005开发环境配置
   [工具\选项]，弹出选项对话框，如下图所示。
   
   添加如下包含路径：
   V:\boost\boost_1_48_0
   V:\xerces\xerces-c-src_2_8_0\src
   V:\ace\ace-5.4
   V:\zlib\zlib-1.2.7
   V:\openssl\openssl-1.0.0\include
   V:\sqlite3\sqlite-amalgamation-3071602
   w:/include

添加如下库路径：
V:\boost\boost_1_48_0\stage\lib
V:\ace\ace-5.4\ace\UnicodeDebug
V:\xerces\xerces-c-src_2_8_0\Build\Win32\VC8\Debug
V:\zlib\zlib-1.2.7
V:\openssl\openssl-1.0.0\out32dll.dbg
V:\sqlite3\sqlite-amalgamation-3071602\win32\Debug
W:\lib

1. 如何构建
   5.1. Linux
   略。
   5.2. Windows
   打开src/kiwi/kiwi.sln。
   先编译libkiwi、libsec，然后分别编译各插件和框架
2. 依赖
   kiwi依赖于boost，使用了boost的通信、线程、定时器、文件操作
   kiwi依赖于xerces-c实现对xml的封装
   kiwi依赖于ACE，使用了线程安全的hash表和task框架。Kiwi准备彻底解除对ACE的依赖，ACE将退出kiwi的历史舞台。
   未来的依赖项：
   kiwi依赖于openssl
   kiwi依赖于zlib，实现压缩功能

3. 成员
   7.1. libkiwi
   插件开发库，提供定时器、线程、日志、通信、字符串、数据库、xml等功能。
   7.2. kiwi
   应用程序运行时框架
   7.3. network
   通信服务插件
   7.4. db
   数据库访问服务插件
   7.5. job
   计划任务服务插件

4. 开发插件
   一个最小插件的文件清单（以demo命名插件类为例）

文件名 描述
demo.vcproj Vs2005工程文件
Makefile Linux MakeFile文件
demo.def Vs2005符号导出文件
demo.h 插件类头文件
demo.cpp 插件类实现文件

8.1. 新建工程

选择“Win32项目”

应用程序类型选择“Dll”，附加选项勾选“空项目”。
8.2. 创建和设置符号导出文件

修改demo.def文件内容，导出CreateModule全局方法，内容如下：
LIBRARY demo
EXPORTS
CreateModule @1

注意：def文件的设置在项目属性页/链接器/输入对话框中，如下图：

8.3. 设置输入库libkiwi.lib

8.4. 编写插件类
插件类必须继承自plugin::PluginModule类，并按需要实现plugin::PluginModule的虚方法。
Demo插件类头文件demo.h代码如下：

ifndef H_DEMO_H

define H_DEMO_H

include “plugin/plugin_module.h”

namespace kiwi{
namespace plugin{
namespace demo{

using namespace util;

class DemoPlugin:public PluginModule{
typedef PluginModule parent;
public:
DemoPlugin();
virtual ~DemoPlugin();
virtual int read_private_config();
virtual int initialize();
virtual int initialized();
virtual int prepare();
virtual int check_valid();
virtual int activate();
virtual int activated();
virtual int deactivate();
virtual int release();
};

};
};
};

endif

其中各方法作用参见基类头文件声明，Demo插件类实现文件demo.cpp代码如下：

include “demo.h”

namespace kiwi{
namespace plugin{
namespace demo{

KIWI_C_API IPluginModule* __stdcall CreateModule(){
return new DemoPlugin();
}

DemoPlugin::DemoPlugin(){}

DemoPlugin::~DemoPlugin(){}

int DemoPlugin::read_private_config(){
return 0;
}

int DemoPlugin::initialize(){
return parent::initialize();
}

int DemoPlugin::initialized(){
return parent::initialized();
}

int DemoPlugin::prepare(){
return parent::prepare();
}

int DemoPlugin::check_valid(){
return parent::check_valid();
}

int DemoPlugin::activate(){
return parent::activate();
}

int DemoPlugin::activated(){
return parent::activated();
}

int DemoPlugin::deactivate(){
return parent::deactivate();
}

int DemoPlugin::release(){
return parent::release();
}

};
};
};

8.5. 编译运行
配置kiwi.conf加载插件

include globle_macros.h

宏名称 功能
KTEXT 宽字符常量，例如:String str = KTEXT(“string”);

9.2. types
int8/uint8/int16/uint16/int32/uint32/int64/uint64/…
real32/real64
byte
pointer
char8/char16/char32
wchar：与平台相关的宽字符类型
uchar:内码unicode字符类型
9.3. util
9.3.1. String

include “util/kstring.h”

常见用法
String str = KTEXT(“Testing ctor”);

String str1 = String::from_local(“ascii”);

ByteArray ba = str.to_local();

wprintf(L”str[1] = TEXT(‘o’):%ls\n”,str.to_wchar().data());
ByteArray ba = str.to_wchar();

String::itoa(-1216473392,ut,sizeof(ut),10);
…

9.3.2. StringFormat

include “util/format.h”

String str1 = StringFormat(KTEXT(“%88%%end.%”)).arg(128).arg(KTEXT(“Testok**”));
9.3.3. Stopwatch

include “util/stopwatch.h”

9.3.4. Timer

include “util/timer.h”

void PluginImpl::handle_timeout(){
}

Timer timer;
timer.interval(keepalive_*1000);
timer.handle_timeout(boost::bind(&PluginImpl::handle_timeout,this));
timer.activate();

9.3.5. ScheduleJob
计划任务类

include “util/schedule_job.h”

void PluginImpl::job_proc(util::ScheduleJob& job){
}

ScheduleJob* job = new ScheduleJob(KTEXT(“job1”));
job->schedule(KTEXT(“* * * * *”));
job->execute(boost::bind(&PluginImpl::job_proc,this,_1));
job->activate();

Schedule语法与crontab一致，举例如下：
* * * * * ：每天每时每分钟执行
1-3,30,31 * * * *：每天每时的1-3分钟或者第30分钟或者第31分钟执行
0-29/1,30-59/2 * * * *：每天每时的0-29分钟内每1分钟执行，30-59分钟内每2分钟执行
* 16 * * * ：每天16点的每分钟执行

9.4. network
9.4.1. MessageBlock

include “network/message_block.h”

适用于协议栈上数据包的高效传递
9.5. db
9.5.1. odbc{}
9.5.2. ScopedConnection

include “db/scoped_db.h”

异常安全的带作用范围的数据库连接对象。
9.5.3. ScopedRecordset

include “db/scoped_db.h”

异常安全的带作用范围的数据集对象。
9.5.4. ScopedCommand

include “db/scoped_db.h”

异常安全的带作用范围的命令对象。

9.6. xml
9.6.1. XMLDocument

include “xml/xml_dom_accessor.h”

9.6.2. XMLNode

include “xml/xml_dom_accessor.h”

9.7. log
9.7.1. Trace

include “log/trace.h”

TRACE(KTEXT(“模块名”),KTEXT(“函数名”);

9.7.2. Logger

include “log/log.h”

Log(KTEXT(“模块名”),StringFormat(KTEXT(“server % is closing.\n”)).arg(1000));

9.8. thread
Thread
ThreadPool
TrheadGroup
Task

9.8.1. Synchronize

include “thread/synchronize.h”

Synchronize sync;
///<阻塞线程，直到超时
sync.wait(0);
///<唤醒一个线程
sync.notify_one();
///<唤醒所有的线程
sync.notify_all();

1. Unicode开发注意事项
   10.1. 源文件编码格式
   源文件统一在vs2005环境下编码，源文件中不要使用中文常量。

10.2. 字符串的使用
程序内部统一使用kiwi::util::String类存储字符串，所有涉及字符串的形参都使用String，尽量不用使用char*,wchar_t*,uchar*,wchar*等指针形式传递。正确的用法是：

virtual int get_field_value(int index,String& val);

void address(const String& val);

virtual const String& name();

String& name();

10.3. 屏幕输出
1） 不要混合使用printf/wprintf
2） 统一使用wprintf
3） 输出宽字符采用%ls
wprintf(L”%ls\n”,str.to_wchar().data());

4） 输出本地多字节字符采用%s
wprintf(L”%s\n”,str.to_local().data());

1. 64位开发注意事项
   涉及与类型大小相关的代码时，统一采用kiwi::types下的类型。
2. 跨平台开发注意事项
   1)
   C++规定，引用嵌套模版类的内部类型（如std::vector::iterator），必须显示告诉编译器这是个type而不是variable。
   例如
   typename std::vector

include

include