Awesome

Yar C Framework

(see also: Yar PHP framework, Yar Java framework)

Requirement

• libevent
• msgpack

Install

./configure --with-msgpack=/path-to-msgpack --with-event=/path-to-libevent
make 

Example

you can find a example in example folder

Manual

Example

当Yar成功安装以后, example目录下有一个简单的例子, 会有助于学习基于Yar的开发.

服务端编程API

如果你是要基于Yar for C开发一个C服务, 那么Yar_Server是你要关心的API, Yar for C(以下简称Yar), 它基于libevent和msgpack, 为开发者提供了daemon, pre-fork, socket manipulation, logging, pack/unpack等作为一个Server常用的功能.

yar_server_init

 int yar_server_init(char *hostname);

初始化Yar_Server, 参数为一个字符串的监听地址, 比如对于IPV4来说类似:localhost:8888, 127.0.0.1:8888, 必须包含端口号.

对于Unix domain socket来说, 类似: /tmp/yar.sock

如果成功返回1, 失败返回0.

我们也能看到, 并没有Server实例返回, 也就是说, 一个进程只能存在一个Server实例. 这点要注意.

yar_server_set_opt

 int yar_server_set_opt(yar_server_opt opt, void *val);

设置Server的参数, 可选的参数有:

typedef enum _yar_server_opt {

  YAR_STAND_ALONE,  //是否单例启动, 一般用作调试的时候, 不会fork worker

  YAR_READ_TIMEOUT,  //读取请求的超时值

  YAR_PARENT_INIT,   //父进程初始化Hook

  YAR_CHILD_INIT,    //Woker进程初始化Hook

  YAR_CHILD_USER,   //Woker运行的用户名

  YAR_CHILD_GROUP,  //Woker运行的group名

  YAR_CUSTOM_DATA,  //回调函数自定义参数

  YAR_MAX_CHILDREN, //pre-fork的worker数目, 必须在1~128之间,

                    //一般设置为和CPU核数相同即可

  YAR_PID_FILE,    //PID文件的产生路径, 默认为空

  YAR_LOG_LEVEL,   //LOG的级别, 默认为ALL

  YAR_LOG_FILE    //日志文件, 日志文件可以为普通文件, 也可以是ronolog

} yar_server_opt;

对于不同的选项, val应该是选项的一级指针, 比如, 设置timeout

 #include "yar.h"

 Int timeout = 5;

 yar_server_setopt(YAR_READ_TIMEOUT, &timeout);

成功返回1, 失败返回0

YAR_STAND_ALONE

是否以单进程启动, 一般用在调试的时候, 因为默认的yar server会以daemon, 并且prefork一些子进程出来, 不利于开发调试.

YAR_READ_TIMEOUT,

请求和处理的超时值, 默认为5s

YAR_PARENT_INIT & YAR_CUSTOM_DATA

Yar server会prefork一些子进程, 这个hook容许我们在yar server prefork完成以后, 对于master进程会做一些初始化的工作, 如果我们设置了这个值, 那么yar在做master进程的初始化工作之后, 也会在master进程调用这个hook, 以方便我们做一些只有master进程需要做的初始化工作.

这个方法的原型是:

 typedef void (*yar_init) (void *data);

这里要关心的就data, data是一个void* 指针, 如果我们通过YAR_CUSTOM_DATA设置过一个自定义的数据, 那么这个指针就是我们最初设置的这个数据的指针.

主要用作在整个yar_server运行过程中, 传递一些我们自定义的数据.

YAR_CHILD_INIT

同上, 不过是worker进程初始化的时候被调用. 函数原型也和parent init一样. 也支持自定义数据.

YAR_CHILD_USER & YAR_CHILD_GROUP

如果设置了, 那么我们的worker进程就会尝试setuid/setgid到这个用户/组运行.

YAR_MAX_CHILDREN

要prefork的子进程数目, 一般设置为和CPU的核数相当即可.

YAR_LOG_FILE & YAR_LOG_LEVEl

Yar server默认的时候会输出一些日志信息, 但是当yar以正常模式启动的时候, 会以daemon模式运行, 这样一来就无法输出日志信息到stderr/stdout.

所以, 需要设置一个文件/管道日志输出目的地.

这个选项支持文件, 或者管道, 对于文件自然没有什么好说, 对于管道的话, 主要结合cronolog来使用.

比如:

 "|/home/huixinchen/local/cronolog/sbin/cronolog ./yar_server_%M.log"

就是说, 日志输出到当前目录的yar_server_*.log, *是当前分钟, 也就是说日志会以分钟做分割.

而对于log level来说, Yar 分为YAR_DEBUG, YAR_NOTICE, YAR_WARN, YAR_ERROR 5个级别的日志级别.

当要输出日志的级别大于log level则输出, 否不输出, 所以这个选项是用作过滤输出的.

yar_server_get_opt

void * yar_server_get_opt(yar_server_opt opt);

获取某个选项的值

成功返回指针的抽象指针, 失败返回NULL

yar_server_register_handler

int yar_server_register_handler(yar_server_handler *handlers);

注册一个服务函数, 服务函数的原型是:

typedef void (*yar_handler) (yar_request *request, yar_response *response, void *data);

而, yar_server_handler的定义是:

typedef struct _yar_server_handler {

  char *name;

  int len;

  yar_handler handler;

} yar_server_handler;

其中name就是RPC调用的时候的方法名, 比如:

yar_server_handler example_handlers[] = {

  {"default", sizeof("default") - 1, yar_handler_example},

  {NULL, 0, NULL}

};

那么当客户端的RPC请求default方法的时候, yar_handler_example就会被调用, 去处理这个请求. 以PHP客户端为例:

<?php
   $yar = new Yar_Client(“tcp://127.0.0.1”);
   $yar->default($args); // yar_handler_example会处理该请求
?>

成功返回1, 失败返回0

yar_server_run

int yar_server_run();

开始运行Server, 这个调用将会开始pre-fork, listening, accpt, process流程.

除非Server被shutdown, 否则这个函数不会返回.

yar_server_shutdown

void yar_server_shutdown();

关闭Server, 这个会停止accpt新请求, worker会在处理完当前请求以后退出

yar_server_destroy

void yar_server_destroy();

销毁Server

客户端编程API

如果, 你是希望请求一个已有的Yar_Server, 那么Yar_Client是你要关心的, 它会请求一个Yar_Server, 并且得到返回.

yar_client_init

yar_client * yar_client_init(char *hostname);

实例化一个Yar_Client, 参数是目的地址

成功返回Yar_Client实例:

struct _yar_client {

  int fd;

  char *hostname;

  yar_client_call call;

};

一般的, 我们不用关心这个结构体的内容, 只需要关心yar_client_call的原型:

typedef yar_response * (*yar_client_call)(yar_client *client, char *method, uint num_args, yar_packager *packager[]);

也就是说, 当得到一个Client实例以后, 我们就可以对Server发起调用, 比如我们调用Server的default方法, 并且有2个参数, 那么就类似

yar_client *client = yar_client_init("tcp://localhost:2222");
yar_response *response = client->call(client, "default", 2, args);

如果, 失败返回NULL, 比如Server不能连接等.

yar_client_destroy

void yar\_client\_destroy(yar\_client \*client);

调用完成后, 销毁一个Yar_Client实例

参数和返回值

Yar采用msgpack作为打包协议, 并且为开发者封装了一系列简单的API来实现对数据的打包解包

解包的相关API

观察之前的

typedef void (*yar_handler) (yar_request *request, yar_response *response, void *data),

我们看到, 当请求到来的时候, 我们Server端注册的处理函数被调用, 其中俩个参数分别为yar_request, 和yar_response.

这个时候, 我们首先要关心的是客户端调用传来了几个参数, 参数分别是什么, 参数的信息保存在request->in里面, 它是个yar_data 指针.

在这里我们不用关心yar_data的结构体的组成是什么, 因为我们只需要调用一系列API就可以得到参数.

Yar协议规定, 所有的参数都打包在一个数组里面, 所以request->in是一个数组.

于是, 如果我要检查当前的参数个数, 那么就调用:

yar_data_type yar_unpack_data_type(const yar_data *data, uint *size);

其中, yar_data_type是一个unum, 可选值是:

typedef enum _yar_data_type {

  YAR_DATA_NULL = 1,

  YAR_DATA_BOOL,

  YAR_DATA_LONG,

  YAR_DATA_ULONG,

  YAR_DATA_DOUBLE,

  YAR_DATA_STRING,

  YAR_DATA_MAP,

  YAR_DATA_ARRAY

} yar_data_type;

对于, string, map, 和array, yar_unpack_data_type的第一个参数将会返回他们的长度或者是元素个数, 比如对于

map {'k' => 'v'},

那么. 返回的size是1.

现在我们就知道怎么检查参数个数了吧, 假设我们的例子只接受3个参数

uint size = 0;

if (yar_unpack_data_type(request->in, &size) != YAR_DATA_ARRAY || size != 3) {  
	yar_response_set_error(response, YAR_ERROR, "参数检查失败, 只接受3个参数");
  	return ;
}

假设我们现在参数已经检查通过, 假设我们接受2个参数, 分别是俩个整数.

那么就通过如下形式获得相关参数内容:

uint arg[2], dummy;

yar_data *tmp;

const yar_data *parameters = yar_request_get_parameters(request);

yar_unpack_iterator *it = yar_unpack_iterator_init(parameters); //生成迭代器

int index = 0;

do {

 tmp = yar_unpack_iterator_current(it);

 if (yar_unpack_data_type(tmp, &dummy) != YAR_DATA_LONG) {

  yar_response_set_error(response, YAR_ERROR, "参数检查失败, 只接受整数");

  return ;

 }

 

 arg[index++] = *(long *)( yar_unpack_data_value(tmp));

} while(yar_unpack_iterator_next(it));

这样我们的arg就得到了俩个整数参数.

打包的相关API

当我们获得参数, 并且处理完请求以后, 我们需要返回数据给客户端, 这个时候我们就需要和打包的API打交道了. 他们是:

int yar_pack_push_array(yar_packager *packager, uint size);

int yar_pack_push_map(yar_packager *packager, uint size);

int yar_pack_push_null(yar_packager *packager);

int yar_pack_push_bool(yar_packager *packager, int val);

int yar_pack_push_long(yar_packager *packager, long num);

int yar_pack_push_ulong(yar_packager *packager, ulong num);

int yar_pack_push_double(yar_packager *packager, double num);

int yar_pack_push_string(yar_packager *packager, char *str, uint len);

int yar_pack_push_data(yar_packager *packager, yar_data *data);

int yar_pack_push_packager(yar_packager *packager, yar_packager *data);

int yar_pack_to_string(yar_packager *packager, yar_payload *payload);

void yar_pack_free(yar_packager *packager);

不要看函数很多, 但其实很简单. 打包的时候, 是一唯打包顺序, 什么是一维度顺序呢?

比如, 我们要打包如下的格式:

{
 a => [b, c]
 d => e
}

那么打包的过程就是:

yar_packager *pk = yar_pack_start_map( 2); //我们是一个2个kv的MAP

yar_pack_push_string(pk, "a", 1); //压入第一个key, a

yar_pack_push_array(pk, 2);  //压入第一个key对应的一个2个元素的array

yar_push_string (pk, "b", 1);   //第一个元素

yar_push_string (pk, "c", 1);   //第二个元素 此时数组已经填充完毕

yar_push_string(pk, "d", 1);   //压入第二个key d

yar_push_string(pk, "e", 1);   //压入第二个key对应的e

来看一个实际的例子(在example/server.c)

这个API返回了一个3个kv的map给客户端, 第一个元素是status值是long 0

第二个元素是parameters, 传回了客户端请求的参数

第三个是一个map, 返回了一些随意的值.

最后调用yar_response_set_retval设置好返回值, 然后释放内存.

总结

最后, Yar的代码中包含了一个Server 和一个Client的例子, 在example目录下.

目前已经实现了PHP端请求C服务, C服务互相请求, 考虑到PHP只能通过HTTP协议提供RPC服务, 所以C请求PHP的, 还暂时没有开放.