ringbuf

Buffer cincin bebas kunci

Buffer cincin multi-produser tunggal-konsumen (MPSC) yang mendukung operasi jangkauan yang berdekatan dan yang dapat dengan mudah digunakan untuk menyampaikan pesan. Implementasi ditulis dalam C11 dan didistribusikan di bawah lisensi BSD 2-Clause.

API

• int ringbuf_setup(ringbuf_t *rbuf, unsigned nworkers, size_t length)

  • Siapkan buffer cincin baru dengan panjang tertentu. rbuf adalah pointer ke objek buffer cincin buram; Penelepon bertanggung jawab untuk mengalokasikan ruang untuk objek ini. Biasanya, objek akan dialokasikan secara dinamis jika menggunakan utas atau dipesan dalam memori bersama diblokir jika menggunakan proses. Ukuran alokasi untuk objek harus diperoleh dengan menggunakan fungsi ringbuf_get_sizes . Mengembalikan 0 pada kesuksesan dan -1 pada kegagalan.

• void ringbuf_get_sizes(unsigned nworkers, size_t *ringbuf_obj_size, size_t *ringbuf_worker_size)

  • Mengembalikan ukuran ringbuf_t buram dan, secara opsional, struktur ringbuf_worker_t . Ukuran struktur ringbuf_t tergantung pada jumlah pekerja, yang ditentukan oleh parameter nworkers .

• ringbuf_worker_t *ringbuf_register(ringbuf_t *rbuf, unsigned i)

  • Daftarkan pekerja saat ini (utas atau proses) sebagai produsen. Setiap produser harus mendaftar sendiri. i adalah nomor pekerja, mulai dari nol (yaitu harus lebih dari nworkers yang digunakan dalam pengaturan). Saat sukses, mengembalikan pointer ke ringbuf_worker_t terstruktur, yang merupakan bagian dari blok memori ringbuf_t . Kegagalan, kembali NULL .

• void ringbuf_unregister(ringbuf_t *rbuf, ringbuf_worker_t *worker)

  • Batalkan register pekerja yang ditentukan dari daftar produser.

• ssize_t ringbuf_acquire(ringbuf_t *rbuf, ringbuf_worker_t *worker, size_t len)

  • Minta ruang dengan panjang tertentu dalam buffer cincin. Mengembalikan offset di mana ruang tersedia atau -1 pada kegagalan. Setelah data siap (biasanya, ketika menulis ke buffer cincin selesai), fungsi ringbuf_produce harus dipanggil untuk menunjukkannya. Nested mendapatkan panggilan tidak diizinkan.

• void ringbuf_produce(ringbuf_t *rbuf, ringbuf_worker_t *worker)

  • Menunjukkan bahwa kisaran yang diperoleh dalam buffer diproduksi dan siap dikonsumsi.

• size_t ringbuf_consume(ringbuf_t *rbuf, size_t *offset)

  • Dapatkan kisaran yang berdekatan yang siap dikonsumsi. Mengembalikan nol jika tidak ada data yang tersedia untuk dikonsumsi. Setelah data dikonsumsi (biasanya, ketika membaca dari buffer cincin selesai), fungsi ringbuf_release harus dipanggil untuk menunjukkan itu.

• void ringbuf_release(ringbuf_t *rbuf, size_t nbytes)

  • Menunjukkan bahwa rentang yang dikonsumsi sekarang dapat dirilis dan sekarang dapat digunakan kembali oleh produsen.

Catatan

Konsumen akan mengembalikan blok rentang yang diproduksi yang diproduksi yaitu panggilan ringbuf_consume tidak akan mengembalikan rentang parsial. Jika Anda menganggap jangkauan yang diproduksi sebagai pesan, maka konsumen akan mengembalikan blok pesan, selalu berakhir pada batas pesan. Perilaku seperti itu memungkinkan kita untuk menggunakan implementasi buffer cincin ini sebagai antrian pesan.

Implementasi diuji secara luas pada mesin X86 24-core, lihat tes tegangan untuk detail tentang teknik tersebut. Ini juga memberikan contoh bagaimana mekanisme dapat digunakan untuk lewat pesan.

Peringatan

Implementasi buffer cincin ini selalu menyediakan rentang ruang yang berdekatan untuk produser. Ini dicapai dengan pembungkus awal jika kisaran yang diminta tidak sesuai pada akhirnya. Implikasi dari ini adalah bahwa panggilan ringbuf_acquire mungkin gagal jika kisaran yang diminta lebih besar dari setengah dari ukuran buffer. Oleh karena itu, mungkin perlu untuk memastikan bahwa ukuran buffer cincin setidaknya dua kali lebih besar dari ukuran unit produksi maksimum.

Perlu juga dicatat bahwa salah satu pertukaran desain tersebut adalah bahwa konsumen saat ini melakukan pemindaian O (n) pada daftar produsen.

Contoh

Produser:

 if (( w = ringbuf_register ( r , worker_id )) == NULL )
	err ( EXIT_FAILURE , "ringbuf_register" )

...

if (( off = ringbuf_acquire ( r , w , len )) != -1 ) {
	memcpy ( & buf [ off ], payload , len );
	ringbuf_produce ( r , tls );
}

Konsumen:

 if (( len = ringbuf_consume ( r , & off )) != 0 ) {
	process ( & buf [ off ], len );
	ringbuf_release ( r , len );
}