OpenWrt：libubox之ustream

數據結構：

struct ustream_buf {
    struct ustream_buf *next;

    char *data;     /** 指向上次操做buff開始地址 */
    char *tail;     /** 指向未使用buff開始地址 */
    char *end;      /** 指向buf結束地址 */

    char head[];    /** 指向buf開始地址 */
};

struct ustream_buf_list {
    struct ustream_buf *head;       /** 指向第1塊ustream_buf */
    struct ustream_buf *data_tail;  /** 指向未使用的ustream_buf */
    struct ustream_buf *tail;       /** 指向最後的ustream_buf */

    int (*alloc)(struct ustream *s, struct ustream_buf_list *l);

    int data_bytes;    /** 已用存儲空間大小 */

    int min_buffers;   /** 可存儲最小的ustream_buf塊個數 */
    int max_buffers;   /** 可存儲最大的ustream_buf塊個數 */
    int buffer_len;    /** 每塊ustream_buf塊存儲空間大小 */

    int buffers;       /** ustream_buf塊個數 */
};

struct ustream {
    struct ustream_buf_list r, w;
    struct uloop_timeout state_change;
    struct ustream *next;

    /*
     * notify_read: (optional)
     * called by the ustream core to notify that new data is available
     * for reading.
     * must not free the ustream from this callback
     */
    void (*notify_read)(struct ustream *s, int bytes_new);

    /*
     * notify_write: (optional)
     * called by the ustream core to notify that some buffered data has
     * been written to the stream.
     * must not free the ustream from this callback
     */
    void (*notify_write)(struct ustream *s, int bytes);

    /*
     * notify_state: (optional)
     * called by the ustream implementation to notify that the read
     * side of the stream is closed (eof is set) or there was a write
     * error (write_error is set).
     * will be called again after the write buffer has been emptied when
     * the read side has hit EOF.
     */
    void (*notify_state)(struct ustream *s);

    /*
     * write:
     * must be defined by ustream implementation, accepts new write data.
     * 'more' is used to indicate that a subsequent call will provide more
     * data (useful for aggregating writes)
     * returns the number of bytes accepted, or -1 if no more writes can
     * be accepted (link error)
     */
    int (*write)(struct ustream *s, const char *buf, int len, bool more);

    /*
     * free: (optional)
     * defined by ustream implementation, tears down the ustream and frees data
     */
    void (*free)(struct ustream *s);

    /*
     * set_read_blocked: (optional)
     * defined by ustream implementation, called when the read_blocked flag
     * changes
     */
    void (*set_read_blocked)(struct ustream *s);

    /*
     * poll: (optional)
     * defined by the upstream implementation, called to request polling for
     * available data.
     * returns true if data was fetched.
     */
    bool (*poll)(struct ustream *s);

    /*
     * ustream user should set this if the input stream is expected
     * to contain string data. the core will keep all data 0-terminated.
     */
    bool string_data;     /** 此ustream是否爲字符串，true-是；false-否 */
    bool write_error;     /** 寫出錯，true-是；false-否 */
    bool eof, eof_write_done;

    enum read_blocked_reason read_blocked;
};

struct ustream_fd {
    struct ustream stream;
    struct uloop_fd fd;
};

初始/銷燬

/**
 * ustream_fd_init: create a file descriptor ustream (uses uloop) 
 */
void ustream_fd_init(struct ustream_fd *s, int fd);

/**
 * ustream_init_defaults: fill default callbacks and options 
 */
void ustream_init_defaults(struct ustream *s);

/**
 * ustream_free: free all buffers and data associated with a ustream 
 */
void ustream_free(struct ustream *s);

寫入read buffer：

/*
 * ustream_reserve: allocate rx buffer space
 *      分配len大小的read buffer可用內存空間，與ustream_fill_read()配合使用
 *
 * len: hint for how much space is needed (not guaranteed to be met)
 * maxlen: pointer to where the actual buffer size is going to be stored
 */
char *ustream_reserve(struct ustream *s, int len, int *maxlen);

/**
 * ustream_fill_read: mark rx buffer space as filled 
 *      設置被ustream_reseve()分配read buffer後寫入的數據大小，
 *      回調notify_read()接口，表示有數據可讀
 */
void ustream_fill_read(struct ustream *s, int len);

讀出read buffer（通常在notify_read()回調接口使用）：

/* 
 * ustream_get_read_buf: get a pointer to the next read buffer data 
 *      獲取新一次寫入的內容，與ustream_consume()配置使用
 */
char *ustream_get_read_buf(struct ustream *s, int *buflen);

/**
 * ustream_consume: remove data from the head of the read buffer 
 */
void ustream_consume(struct ustream *s, int len);

操做write buffer，盡最大能力調用write()回調用接口寫入，若是超出能力將把未寫入的數據存儲在write buffer中。

/* 
 * ustream_write: add data to the write buffer 
 */
int ustream_write(struct ustream *s, const char *buf, int len, bool more);
int ustream_printf(struct ustream *s, const char *format, ...);
int ustream_vprintf(struct ustream *s, const char *format, va_list arg);

把在write buffer中的數據寫入實際地方，調用write()回調接口和notify_write()回調接口。通常在描述符的poll操做中調用，表示當描述符變爲可寫時當即把上一次未寫入的內容進行寫入操做。

/*
 * ustream_write_pending: attempt to write more data from write buffers
 * returns true if all write buffers have been emptied.
 */
bool ustream_write_pending(struct ustream *s);