API Document : fmbuf

Macros

#define FMBUF_SEEK_LEFT  0 // move the target(header/tailer) to the left
#define FMBUF_SEEK_RIGHT 1 // move the target(header/tailer) to the right

APIs

Description

fmbuf can be used as ring-buffer or array, and:

• it's lock-free when there is only one producer(thread A) and one consumer(thread B) and the fmbuf as a ring-buffer

fmbuf_create

fmbuf* fmbuf_create(size_t size)

• brief: create a fmbuf
• param: size the buffer size user want to create
• return:
  • the pointer of fmbuf
  • NULL if create failure when there is no available memory
• note: if the size is 0, it will create a empty fmbuf with size is 0

fmbuf_delete

void fmbuf_delete(fmbuf *mbuf)

• brief: destroy a fmbuf
• param: mbuf pointer of fmbuf
• return: void

fmbuf_size

size_t fmbuf_size(fmbuf *mbuf)

• brief: return the total size of fmbuf
• param: mbuf pointer of fmbuf
• return: the total size of fmbuf

fmbuf_free

size_t fmbuf_free(fmbuf *mbuf)

• brief: return how many bytes left of the fmbuf
• param: mbuf pointer of fmbuf
• return: the unused size of fmbuf

fmbuf_used

size_t fmbuf_used(fmbuf *mbuf)

• brief: return how many bytes used of the fmbuf
• param: mbuf pointer of fmbuf
• return: the used size of fmbuf

fmbuf_clear

void fmbuf_clear(fmbuf *mbuf)

• brief: reset a fmbuf, and it will be a empty fmbuf after that
• param: mbuf pointer of fmbuf
• return: void

fmbuf_head

void* fmbuf_head(fmbuf *mbuf)

• brief: return the header pointer of the fmbuf
• param: mbuf pointer of fmbuf
• return: the header pointer of the fmbuf

fmbuf_tail

void* fmbuf_tail(fmbuf *mbuf)

• brief: return the tailer pointer of the fmbuf
• param: mbuf pointer of fmbuf
• return: the tailer pointer of the fmbuf

fmbuf_realloc

fmbuf* fmbuf_realloc(fmbuf *mbuf, size_t size)

• brief: resize the fmbuf
• param: mbuf pointer of fmbuf
• param: size the new size user want to be
• return: the new fmbuf with the new size
• note: user MUST ALWAYS use the return pointer as the new fmbuf, the old pointer may not available

fmbuf_push

int fmbuf_push(fmbuf *mbuf, const void *data, size_t size)

• brief: push data into mbuf
• param: mbuf pointer of fmbuf
• param: data the data user want to push to mbuf
• param: size the size of data
• return:
  • 0: success
  • 1: failure

fmbuf_pop

int fmbuf_pop(fmbuf *mbuf, void *buf, size_t size)

• brief: pop data from mbuf
• param: mbuf pointer of fmbuf
• param: buf the data will be copied to the user buffer
• param: size the size of the user buf
• note: if the buf is NULL, the data will still be poped up
• return:
  • 0: success
  • 1: failure: the mbuf size < user expected size

fmbuf_vpop

void* fmbuf_vpop(fmbuf *mbuf, void *buf, size_t size)

• brief: pop data from mbuf, but actually almost 99% pop action won't involve the data copy, it just return the data pointer of the real data
• note: user MUST ALWAYS use the return pointer as the data pointer
• param: mbuf pointer of fmbuf
• param: buf the data will be copied to the user buffer (99% it won't copy)
• param: size the size of the user buf
• return: the real data pointer

fmbuf_rawget

void* fmbuf_rawget(fmbuf *mbuf, void *buf, size_t size)

• brief: get the data pointer of raw data, and it won't consume the data, so user still can pop the data later
• note: user MUST ALWAYS use the return pointer as the data pointer
• param: mbuf pointer of fmbuf
• param: buf the data will be copied to the user buffer (99% it won't copy)
• param: size the size of the user buf
• return: the real data pointer

fmbuf_alloc

void* fmbuf_alloc(fmbuf *mbuf, size_t size)

• brief: Allocate a specific size of buffer from the mbuf.
• param: mbuf pointer of fmbuf
• param: size the size user want to allocate
• return:
  • the begin location of the buffer
  • NULL when there is no enough space

fmbuf_head_seek

void fmbuf_head_seek(fmbuf *mbuf, size_t offset, int direction)

• brief: Move the header pointer of the mbuf.
• param: mbuf pointer of fmbuf
• param: offset the distance of user want to move,
• param: direction
  • FMBUF_SEEK_LEFT: move left to the header
  • FMBUF_SEEK_RIGHT: move right to the header
• return: void

fmbuf_tail_seek

void fmbuf_tail_seek(fmbuf *mbuf, size_t offset, int direction)

• brief: Move the tailer pointer of the fmbuf.
• param: mbuf pointer of fmbuf
• param: offset the distance of user want to move,
• param: direction
  • FMBUF_SEEK_LEFT: move left to the tailer
  • FMBUF_SEEK_RIGHT: move right to the tailer
• return: void

fmbuf_rewind

void fmbuf_rewind(fmbuf *mbuf)

• brief: Reset the header pointer to the begin of the mbuf, then move the data and tailer pointer as well.
• param: mbuf pointer of fmbuf
• return: void
• note: it only can be used when the fmbuf as a array

fmbuf_head_free

size_t fmbuf_head_free(fmbuf *mbuf)

• brief: return the how many free space before the header pointer
• param: mbuf pointer of fmbuf
• return: void

fmbuf_tail_free

size_t fmbuf_tail_free(fmbuf *mbuf)

• brief: return the how many free space after the tailer pointer
• param: mbuf pointer of fmbuf
• return: void

fmbuf_empty

bool fmbuf_empty(fmbuf *mbuf)

• brief: return the mbuf is empty or not
• param: mbuf pointer of fmbuf
• return: True/False