rb_destroy

NAME

rb_destroy(3), rb_cleanup(3), rb_stop(3) - stop, destroy and cleanup ring buffer

SYNOPSIS

#include <rb.h>

int rb_destroy(struct rb *rb);
int rb_cleanup(struct rb *rb);

DESCRIPTION

rb_destroy(3) will free() up memory allocated by rb_new(3).

rb_cleanup(3) does nothing unless multi-thread is enabled. You still should call this in every scenario in case you switch rb_init(3) to multi-thread, or library will get updated with some cleaning code in the future.

If rb is multi-thread enabled, functions will destroy thread related objects like semaphores and mutexes.

Cleanup functions are safe to call only when no other thread is using rb object. This may get tricky when you want destroy ring buffer but some pesky thread in blocked in read or write operation. rb_stop(3) will wake all those threads, and read/write functions will start returning with ECANCELED error. You can then join your threads and safely call cleanup function.

RETURN VALUE

0 on success or -1 on errors.

ERROR

EINVAL

rb is NULL

EXAMPLE

Stop threads before destroying ring buffer

/* consumers thread */
void *consumer(void *arg) {
    for (;;) {
        if (rb_read(rb, buf, sizeof(buf)) == -1 && errno == ECANCELED)
            /* return from the thread */
            return NULL;
    }
 }

/* producers thread */
void *producer(void *arg) {
    for (;;) {
        if (rb_write(rb, buf, sizeof(buf)) == -1 && errno == ECANCELED)
            /* return from the thread */
            return NULL;
    }
 }

 /* main thread */
 void main_loop(void) {
     pthread_t cons, prod;

     pthread_create(&cons, NULL, consumer, rb);
     pthread_create(&prod, NULL, consumer, rb);

     wait_for_exit_signal();

     /* wake consumer and producer threads, rb_ functions will start
      * returning ECANCELED errors, and threads will exit */
     rb_stop(rb);

     pthread_join(cons);
     pthread_join(prod);

     /* it's now safe to destroy buffer */
     rb_destroy(rb);
 }

SEE ALSO

rb_new(3), rb_init(3), rb_destroy(3), rb_cleanup(3), rb_write(3), rb_send(3), rb_writev(3), rb_sendv(3), rb_read(3), rb_recv(3), rb_readv(3), rb_recvv(3), rb_read_claim(3), rb_read_commit(3), rb_write_claim(3), rb_write_commit(3), rb_clear(3), rb_discard(3), rb_count(3), rb_space(3), rb_stop(3), rb_peek_size(3), rb_set_hard_max_count(3)