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

協程文件描述符

函數返回值

  無