Yar C Framework
Switch branches/tags
Nothing to show
Clone or download
Latest commit b633f05 Dec 29, 2015
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example fixed make error and warning May 14, 2015
.gitignore fixed make error and warning May 14, 2015
AUTHORS Hello World! Jul 17, 2014
ChangeLog Hello World! Jul 17, 2014
LICENSE Hello World! Jul 17, 2014
Makefile.am Hello World! Jul 17, 2014
Makefile.in Hello World! Jul 17, 2014
README.md update yar_response_set_error in readme May 14, 2015
aclocal.m4 Hello World! Jul 17, 2014
config.guess Hello World! Jul 17, 2014
config.h.in Hello World! Jul 17, 2014
config.sub Hello World! Jul 17, 2014
configure Hello World! Jul 17, 2014
configure.in Hello World! Jul 17, 2014
depcomp Hello World! Jul 17, 2014
install-sh Hello World! Jul 17, 2014
ltmain.sh Hello World! Jul 17, 2014
missing Hello World! Jul 17, 2014
yar.h update yar_response_set_error in readme May 14, 2015
yar_client.c fixed make error and warning May 14, 2015
yar_client.h yar_client without timeout, if server timeout, and tv will be set to … Jul 17, 2014
yar_common.h Hello World! Jul 17, 2014
yar_log.c Hello World! Jul 17, 2014
yar_log.h Hello World! Jul 17, 2014
yar_pack.c update msgpack Dec 29, 2015
yar_pack.h fixed make error and warning May 14, 2015
yar_protocol.c Hello World! Jul 17, 2014
yar_protocol.h Hello World! Jul 17, 2014
yar_request.c Hello World! Jul 17, 2014
yar_request.h Hello World! Jul 17, 2014
yar_response.c Hello World! Jul 17, 2014
yar_response.h Hello World! Jul 17, 2014
yar_server.c update pack & pidfile Dec 29, 2015
yar_server.h Hello World! Jul 17, 2014

README.md

#Yar C 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的, 还暂时没有开放.