cmhi
/
f-stack
mirror of https://github.com/F-Stack/f-stack.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
f-stack/doc/F-Stack_API_Reference.md

225 lines
8.0 KiB
Markdown
Raw Normal View History

init
2017-04-21 10:43:26 +00:00
# F-Stack API Reference
F-Stack is a high performance network framework based on DPDK.
FF API provides standard Kqueue/Epoll interface, and a micro threading framework (SPP).
In order to facilitate a variety of services can use F-Stack simpler and faster, F-Stack has integrated Nginx and Redis。
See 《F-Stack\_Nginx\_APP\_Guide》, 《F-Stack\_Reis\_APP\_Guide》, 《F-Stack\_Microthread\_APP\_Guide》
## FF API
The header file ff_api.h defines the following API, which should be used to replace the system called when using the F-Sstack.
### Initialize
#### ff_init
int ff_init(const char *conf, int argc, char * const argv[]);
conf:Profile path
argv：-c <coremask>,the coremask parameters can cover the coremask in configuration file
Initialize F-Stack，include DPDK/FreeBSD network stack, etc.
#### ff_run
void ff_run(loop_func_t loop, void *arg);
loop is a callbask function，the service logic is implemented by the user, and be called by each poll of F-Stack .
### Control API
#### ff_fcntl
int ff_fcntl(int fd, int cmd, ...);
fcntl() performs one of the operations described below on the open file descriptor fd. The operation is determined by cmd.
more info see man fcntl
#### ff_sysctl
int ff_sysctl(const int *name, u_int namelen, void *oldp, size_t *oldlenp,
const void *newp, size_t newlen);
ff_sysctl is used to modify kernel parameters at runtime.
However, it is currently only supported before F-Stack is started.
#### ff_ioctl
int ff_ioctl(int fd, unsigned long request, ...);
The ioctl() function manipulates the underlying device parameters of special files.
more info see man ioctl
### Network API
#### ff_socket
int ff_socket(int domain, int type, int protocol);
creates an endpoint for communication and returns a file descriptor that refers to that endpoint.
more info see man socket
#### ff_setsockopt & ff_getsockopt
int ff_getsockopt(int s, int level, int optname, void *optval,
socklen_t *optlen);
int ff_setsockopt(int s, int level, int optname, const void *optval,
socklen_t optlen);
getsockopt() and setsockopt() manipulate options for the socket referred to by the file descriptor sockfd.
more info see man getsockopt and man setsockopt.
#### ff_socketpair
int ff_socketpair(int domain, int type, int protocol, int *sv);
The socketpair() call creates an unnamed pair of connected sockets in the specified domain, of the specified type, and using the optionally specified protocol.
more info see man socketpair
#### Socket operation function
int ff_listen(int s, int backlog);
int ff_bind(int s, const struct linux_sockaddr *addr, socklen_t addrlen);
int ff_accept(int s, struct linux_sockaddr *addr, socklen_t *addrlen);
int ff_connect(int s, const struct linux_sockaddr *name, socklen_t namelen);
int ff_close(int fd);
int ff_shutdown(int s, int how);
Socket operation function, more info see Linux Programmer's Manual.
#### ff_getpeername
int ff_getpeername(int s, struct linux_sockaddr *name, socklen_t *namelen);
ff_getpeername() returns the address of the peer connected to the socket sockfd, in the buffer pointed to by addr.
more info see man getpeername.
#### ff_getsockname
int ff_getsockname(int s, struct linux_sockaddr *name,
socklen_t *namelen);
ff_getsockname() returns the current address to which the socket sockfd is bound, in the buffer pointed to by addr.
more info see man getsockname.
#### ff\_read & ff\_readv
ssize_t ff_read(int d, void *buf, size_t nbytes);
ssize_t ff_readv(int fd, const struct iovec *iov, int iovcnt);
read() attempts to read up to count bytes from file descriptor fd into the buffer starting at buf.
more info see man read and man readv.
#### ff\_write & ff\_writev
ssize_t ff_write(int fd, const void *buf, size_t nbytes);
ssize_t ff_writev(int fd, const struct iovec *iov, int iovcnt);
write() writes up to count bytes from the buffer pointed buf to the file referred to by the file descriptor fd.
more info see man write and man readv.
#### ff\_send & ff\_sendto & ff\_sendmsg
ssize_t ff_send(int s, const void *buf, size_t len, int flags);
ssize_t ff_sendto(int s, const void *buf, size_t len, int flags, const struct linux_sockaddr *to, socklen_t tolen);
ssize_t ff_sendmsg(int s, const struct msghdr *msg, int flags);
send a message on a socket.
more info see man send.
#### ff\_recv & ff\_recvfrom & ff\_recvmsg
ssize_t ff_recv(int s, void *buf, size_t len, int flags);
ssize_t ff_recvfrom(int s, void *buf, size_t len, int flags, struct linux_sockaddr *from, socklen_t *fromlen);
ssize_t ff_recvmsg(int s, struct msghdr *msg, int flags);
receive a message from a socket.
more info see man recv.
#### ff_select
int ff_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);
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).
more info see man select.
#### ff_poll
int ff_poll(struct pollfd fds[], nfds_t nfds, int timeout);
wait for some event on a file descriptor.
more info see man poll.
### Kqueue API
#### ff_kqueue
int ff_kqueue(void);
int ff_kevent(int kq, const struct kevent *changelist, int nchanges, struct kevent *eventlist, int nevents, const struct timespec *timeout);
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.
more info see man kqueue on FreeBSD System Calls Manual.
### Epoll API
#### ff\_epoll\_create
int ff_epoll_create(int size);
epoll_create() returns a file descriptor referring to the new epoll instance.
more info see man epoll_create.
#### ff\_epoll\_ctl
int ff_epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
This system call performs control operations on the epoll(7) instance referred to by the file descriptor epfd.
more info see man epoll_ctl.
### Micro Thread API `micro_thread/mt_api.h`
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.
#### UDP send/recv interface
int mt_udpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int& buf_size, int timeout);
Use Random socket port to send and recv udp packet.
#### tcp send/recv interface
​
int mt_tcpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int& buf_size, int timeout, MtFuncTcpMsgLen chek_func);
Use connection pool to send and recv tcp packet, keep-alive default are 10 mintues. The parameter of buf can't use `static`.
​
enum MT\_TCP\_CONN\_TYPE
{
MT\_TCP\_SHORT = 1,
MT\_TCP\_LONG = 2,
MT\_TCP\_SHORT\_SNDONLY = 3,
MT\_TCP\_LONG\_SNDONLY = 4,
MT\_TCP\_BUTT
};
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);
Tcp send and recv interface, you can choose if the connection is keep-alive or close.The parameter of buf can't use `static`.
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);
Tcp send and recv interface, you can choose if the connection is keep-alive or close.The parameter of buf can't use `static`.
​
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);
Use connection pool to send and recv tcp packet, keep-alive default are 10 mintues. The parameter of buf can't use `static`.
#### Socet API of micro thread
see `micro_thread/mt_api.h`.