1# F-Stack API Reference 2 3F-Stack is a high performance network framework based on DPDK. 4 5FF API provides standard Kqueue/Epoll interface, and a micro threading framework (SPP). 6 7In order to facilitate a variety of services can use F-Stack simpler and faster, F-Stack has integrated Nginx and Redis。 8 9See 《F-Stack\_Nginx\_APP\_Guide》, 《F-Stack\_Reis\_APP\_Guide》, 《F-Stack\_Microthread\_APP\_Guide》 10 11## FF API 12 13 The header file ff_api.h defines the following API, which should be used to replace the system called when using the F-Sstack. 14 15### Initialize 16 17#### ff_init 18 19 int ff_init(const char *conf, int argc, char * const argv[]); 20 conf:Profile path 21 argv：-c <coremask>,the coremask parameters can cover the coremask in configuration file 22 23 Initialize F-Stack，include DPDK/FreeBSD network stack, etc. 24 25#### ff_run 26 27 void ff_run(loop_func_t loop, void *arg); 28loop is a callbask function，the service logic is implemented by the user, and be called by each poll of F-Stack . 29 30### Control API 31 32#### ff_fcntl 33 34 int ff_fcntl(int fd, int cmd, ...); 35 36 fcntl() performs one of the operations described below on the open file descriptor fd. The operation is determined by cmd. 37more info see man fcntl 38 39#### ff_sysctl 40 41 int ff_sysctl(const int *name, u_int namelen, void *oldp, size_t *oldlenp, 42 const void *newp, size_t newlen); 43 44 ff_sysctl is used to modify kernel parameters at runtime. 45However, it is currently only supported before F-Stack is started. 46 47#### ff_ioctl 48 49 int ff_ioctl(int fd, unsigned long request, ...); 50 51 The ioctl() function manipulates the underlying device parameters of special files. 52 more info see man ioctl 53 54### Network API 55 56#### ff_socket 57 58 int ff_socket(int domain, int type, int protocol); 59 60 creates an endpoint for communication and returns a file descriptor that refers to that endpoint. 61 more info see man socket 62 63#### ff_setsockopt & ff_getsockopt 64 65 int ff_getsockopt(int s, int level, int optname, void *optval, 66 socklen_t *optlen); 67 int ff_setsockopt(int s, int level, int optname, const void *optval, 68 socklen_t optlen); 69 70 getsockopt() and setsockopt() manipulate options for the socket referred to by the file descriptor sockfd. 71 more info see man getsockopt and man setsockopt. 72 73#### ff_socketpair 74 75 int ff_socketpair(int domain, int type, int protocol, int *sv); 76 77 The socketpair() call creates an unnamed pair of connected sockets in the specified domain, of the specified type, and using the optionally specified protocol. 78 more info see man socketpair 79 80#### Socket operation function 81 82 int ff_listen(int s, int backlog); 83 int ff_bind(int s, const struct linux_sockaddr *addr, socklen_t addrlen); 84 int ff_accept(int s, struct linux_sockaddr *addr, socklen_t *addrlen); 85 int ff_connect(int s, const struct linux_sockaddr *name, socklen_t namelen); 86 int ff_close(int fd); 87 int ff_shutdown(int s, int how); 88 89 Socket operation function, more info see Linux Programmer's Manual. 90 91#### ff_getpeername 92 93 int ff_getpeername(int s, struct linux_sockaddr *name, socklen_t *namelen); 94 95 ff_getpeername() returns the address of the peer connected to the socket sockfd, in the buffer pointed to by addr. 96 more info see man getpeername. 97 98#### ff_getsockname 99 100 int ff_getsockname(int s, struct linux_sockaddr *name, 101 socklen_t *namelen); 102 103 ff_getsockname() returns the current address to which the socket sockfd is bound, in the buffer pointed to by addr. 104 more info see man getsockname. 105 106#### ff\_read & ff\_readv 107 108 ssize_t ff_read(int d, void *buf, size_t nbytes); 109 ssize_t ff_readv(int fd, const struct iovec *iov, int iovcnt); 110 111 read() attempts to read up to count bytes from file descriptor fd into the buffer starting at buf. 112 more info see man read and man readv. 113 114#### ff\_write & ff\_writev 115 116 ssize_t ff_write(int fd, const void *buf, size_t nbytes); 117 ssize_t ff_writev(int fd, const struct iovec *iov, int iovcnt); 118 119 write() writes up to count bytes from the buffer pointed buf to the file referred to by the file descriptor fd. 120 more info see man write and man readv. 121 122#### ff\_send & ff\_sendto & ff\_sendmsg 123 124 ssize_t ff_send(int s, const void *buf, size_t len, int flags); 125 ssize_t ff_sendto(int s, const void *buf, size_t len, int flags, const struct linux_sockaddr *to, socklen_t tolen); 126 ssize_t ff_sendmsg(int s, const struct msghdr *msg, int flags); 127 128 send a message on a socket. 129 more info see man send. 130 131#### ff\_recv & ff\_recvfrom & ff\_recvmsg 132 133 ssize_t ff_recv(int s, void *buf, size_t len, int flags); 134 ssize_t ff_recvfrom(int s, void *buf, size_t len, int flags, struct linux_sockaddr *from, socklen_t *fromlen); 135 ssize_t ff_recvmsg(int s, struct msghdr *msg, int flags); 136 137 receive a message from a socket. 138 more info see man recv. 139 140#### ff_select 141 142 int ff_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); 143 144 select() allow a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" for some class of I/O operation (e.g., input possible). 145 more info see man select. 146 147#### ff_poll 148 149 int ff_poll(struct pollfd fds[], nfds_t nfds, int timeout); 150 151 wait for some event on a file descriptor. 152 more info see man poll. 153 154### Kqueue API 155 156#### ff_kqueue 157 158 int ff_kqueue(void); 159 int ff_kevent(int kq, const struct kevent *changelist, int nchanges, struct kevent *eventlist, int nevents, const struct timespec *timeout); 160 161 The kqueue() system call provides a generic method of notifying the user when an event happens or a condition holds, based on the results of small pieces of kernel code termed filters. 162 more info see man kqueue on FreeBSD System Calls Manual. 163 164### Epoll API 165 166#### ff\_epoll\_create 167 168 int ff_epoll_create(int size); 169 170 epoll_create() returns a file descriptor referring to the new epoll instance. 171 more info see man epoll_create. 172 173#### ff\_epoll\_ctl 174 175 int ff_epoll_ctl(int epfd, int op, int fd, struct epoll_event *event); 176 177 This system call performs control operations on the epoll(7) instance referred to by the file descriptor epfd. 178 more info see man epoll_ctl. 179 180### Micro Thread API `micro_thread/mt_api.h` 181 182 In order to develop asynchronous program convenient without complex asynchronous logic processing, reference [SPP's micro thread framework](https://github.com/Tencent/MSEC/tree/master/spp_rpc) F-Stack provides a micro thread framework, synchronous programming can be achieved using the asynchronous call. 183 184#### UDP send/recv interface 185 186 int mt_udpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int& buf_size, int timeout); 187 188 Use Random socket port to send and recv udp packet. 189 190 191#### tcp send/recv interface 192 193 int mt_tcpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int& buf_size, int timeout, MtFuncTcpMsgLen chek_func); 194 195 Use connection pool to send and recv tcp packet, keep-alive default are 10 mintues. The parameter of buf can't use `static`. 196 197 198 enum MT_TCP_CONN_TYPE 199 { 200 MT_TCP_SHORT = 1, 201 MT_TCP_LONG = 2, 202 MT_TCP_SHORT_SNDONLY = 3, 203 MT_TCP_LONG_SNDONLY = 4, 204 MT_TCP_BUTT 205 }; 206 207 int mt_tcpsendrcv_ex(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int* buf_size, int timeout, MtFuncTcpMsgLen func, MT_TCP_CONN_TYPE type = MT_TCP_LONG); 208 209 Tcp send and recv interface, you can choose if the connection is keep-alive or close.The parameter of buf can't use `static`. 210 211 212 int mt\_tcpsendrcv\_ex(struct sockaddr_in* dst, void* pkg, int len, void*& rcv_buf, int& recv_pkg_size, int timeout, MtFuncTcpMsgChecker check_func, void* msg_ctx=NULL, MT_TCP_CONN_TYPE type = MT_TCP_LONG, bool keep_rcv_buf=false); 213 214 Tcp send and recv interface, you can choose if the connection is keep-alive or close.The parameter of buf can't use `static`. 215 216 217 int mt_tcpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void*& rcv_buf, int& recv_pkg_size, int timeout, MtFuncTcpMsgChecker check_func, void* msg_ctx=NULL, bool keep_rcv_buf=false); 218 219 220 Use connection pool to send and recv tcp packet, keep-alive default are 10 mintues. The parameter of buf can't use `static`. 221 222#### Socet API of micro thread 223 224 see `micro_thread/mt_api.h`. 225