srs之state thread库接口分析

1.协程

  协程是一种程序组件（以下称为微线程），通常我们把协程理解为自己实现调度，用于提高程序运行效率，降低开发复杂度的微线程。协程在用户态实现代码段的调度，不需要像线程一样切换到内核态进行调度，降低了对系统调度的依赖，减少了大量的中断和换页操作，从而降低了开发复杂度。开发者可以用同步的方式去进行代码开发，不需要考虑多线程模型的线程调度和诸多临界资源竞争问题。
  协程在处理异步等待事件时有很大的优势，如IO的读写操作往往比较耗时，CPU在遇到IO操作时需要切换线程，等待IO事件准备好之后再继续执行IO操作，如socket的连接，数据的收发，及文件的读写等都是比较频繁却比较耗时的操作，使用协程可以直接再用户态切换微线程，大大降低了微线程直接的调度过程，提高了代码的运行效率。

2.ST的结构

2.1 st_thread

  微线程上下文信息结构体，用于创建微线程执行代码段。

2.2 queue

  RUNQ：队列中存储的是可以被调度运行的微线程，每次调度_st_vp_schedule即从该队列取出一个st_thread去运行。
  IOQ：存储处于IO等待状态的threads，当上层调用st_poll时，将该thread放入IOQ中；当底层epoll有IO事件到达时，将该thread从IOQ中移除，并放入RUNQ中。
  ZOMBIEQ：当st_thread退出时，放入ZOMBIEQ队列中
  SLEEPQ:当st_poll传入大于0的超时参数或者调用st_usleep和st_cond_timewait时，将thread加入到SLEEPQ中。

2.3 st_poll

  用于监听各种IO事件，会根据系统能力不同而进行切换（kqueue、epoll、poll、select）

2.4 timer

  用于记录各种超时和st_sleep

2.5 vp_schedule

  微线程调度切换函数，每次调用都会完成一次微线程切换。

3 接口详解

3.1 st_set_eventsys

函数原型：

int st_set_eventsys(int eventsys)

函数描述

  设置协程事件通知机制，linux下用epoll，BSD使用kqueue。

参数-eventsys

  事件通知机制类型，取值如下：
ST_EVENTSYS_DEFAULT(0) ：使用库默认事件通知机制
ST_EVENTSYS_SELECT(1) ：使用select事件通知机制
ST_EVENTSYS_POLL(2) ：使用poll事件通知机制
ST_EVENTSYS_ALT(3) ：使用alternate备用的事件通知机制

函数返回值

  成功返回0，失败返回-1

3.2 st_get_eventsys

函数原型：

int st_get_eventsys(void)

函数描述

  获取协程事件通知机制，linux下用epoll，BSD使用kqueue。

函数返回值

  事件通知机制类型，取值如下：
ST_EVENTSYS_DEFAULT(0) ：使用库默认事件通知机制
ST_EVENTSYS_SELECT(1) ：使用select事件通知机制
ST_EVENTSYS_POLL(2) ：使用poll事件通知机制
ST_EVENTSYS_ALT(3) ：使用alternate备用的事件通知机制

3.3 st_get_eventsys_name

函数原型：

const char *st_get_eventsys_name(void)

函数描述

  获取协程事件通知机制的函数名称

函数返回值

  返回协程事件通知机制的函数名称，如epoll、kqueue、select、poll等

3.4 st_init

函数原型：

int st_init(void)

函数描述

  初始化协程库全局变量、队列、事件通知机制，并创建一个空闲协程

函数返回值

  成功返回0，失败返回-1

3.5 _st_netfd_new

函数原型：

_st_netfd_t *_st_netfd_new(int osfd, int nonblock, int is_socket)

函数描述

  根据文件描述符创建一个协程描述符结构体

参数-osfd

文件描述符句柄

参数-nonblock

是否阻塞，1为阻塞，0为非阻塞

参数-is_socket

是否是socket，1为socket，0为非socket

函数返回值

  成功返回0，失败返回-1

3.6 st_netfd_poll

函数原型：

int st_netfd_poll(_st_netfd_t *fd, int how, st_utime_t timeout)

函数描述

  让协程等待IO事件的到来，协程将停止执行，直到IO事件到来在继续执行。

参数-fd

协程文件描述符指针

参数-how

等待事件类型，取值如下：
POLLIN：等待数据写入事件
POLLOUT：等待数据写出事件

参数-timeout

等待超时时间，单位为微妙

函数返回值

  成功返回0，失败返回-1

3.7 st_accept

函数原型：

_st_netfd_t *st_accept(_st_netfd_t *fd, struct sockaddr *addr, int *addrlen, st_utime_t timeout)

函数描述

  非阻塞式接收连接

参数-fd

协程文件描述符指针

参数-addr

  对方socket地址，可为NULL

参数-addrlen

  对方socket地址长度指针，可为NULL

参数-timeout

等待超时时间，单位为微妙

函数返回值

  成功返回0，失败返回-1

3.8 st_connect

函数原型：

int st_connect(_st_netfd_t *fd, const struct sockaddr *addr, int addrlen, st_utime_t timeout)

函数描述

  非阻塞式接连接socket

参数-fd

协程文件描述符指针

参数-addr

  对方socket地址

参数-addrlen

  对方socket地址长度指针

参数-timeout

等待超时时间，单位为微妙

函数返回值

  成功返回0，失败返回-1

3.9 st_read

函数原型：

ssize_t st_read(_st_netfd_t *fd, void *buf, size_t nbyte, st_utime_t timeout)

函数描述

  非阻塞式读取socket数据

参数-fd

协程文件描述符指针

参数-buf

  接收数据buffer指针

参数-nbyte

  接收buffer大小

参数-timeout

等待超时时间，单位为微妙

函数返回值

  成功返回0，失败返回-1

3.10 st_write

函数原型：

ssize_t st_write(_st_netfd_t *fd, const void *buf, size_t nbyte, st_utime_t timeout)

函数描述

  非阻塞式读取socket数据

参数-fd

协程文件描述符指针

参数-buf

  发送数据buffer指针

参数-nbyte

  发送buffer大小

参数-timeout

等待超时时间，单位为微妙

函数返回值

  成功返回0，失败返回-1

3.10 st_netfd_close

函数原型：

void srs_close_stfd(st_netfd_t& stfd)

函数描述

  关闭协程文件描述符

参数-stfd

协程文件描述符

函数返回值

  无