giouring - about the project

giouring is a Go port of the liburing library. It is written entirely in Go. No cgo.

Almost all functions and structures from liburing was implemented.

• giouring versioning is aligned with liburing versioning.
• giouring is currently up to date with liburing commit: e1e758ae8360521334399c2a6eace05fa518e218

The giouring API is very similar to the liburing API, so anyone familiar with liburing will find it easier when writing code. Significant changes include:

• Method and structure names have been aligned with the naming conventions of the Go language.
• The prefix io_uring has been removed from method and structure names. After importing the package, methods and types will be preceded by the library name: giouring.
• SQE and CQE types have been given full names: SubmissionQueueEntry and CompletionQueueEvent.
• Additionally, if a method primarily pertains to a specific structure, for example, all methods prefixed with io_uring_prep that are related to the SubmissionQueueEntry structure (in liburing: io_uring_sqe), the pointer that was passed in C as a method argument has been moved to the method receiver.

Important notice

• giouring was tested on kernel version 6.2.0-27-generic. Keep in mind that when running unit tests on older kernel versions, some tests may fail because the older kernel may not support some functionality. This will be fixed in the future.
• Test coverage is currently low, but it will be systematically expanded.

Documentation

(back to top)

Used by

• Gain - a high-performance io_uring networking framework written entirely in Go.

(back to top)

Prerequisites

Gain requires Go 1.20+

(back to top)

Implemented structs

liburing name	Golang liburing port name	Notes	Implemented
io_uring_sq	SubmissionQueue		:heavy_check_mark:
io_uring_cq	CompletionQueue		:heavy_check_mark:
io_uring	Ring		:heavy_check_mark:
io_uring_sqe	SubmissionQueueEntry		:heavy_check_mark:
io_uring_cqe	CompletionQueueEvent		:heavy_check_mark:
io_sqring_offsets	SQRingOffsets		:heavy_check_mark:
io_cqring_offsets	CQRingOffsets		:heavy_check_mark:
io_uring_params	Params		:heavy_check_mark:
io_uring_files_update	FilesUpdate		:heavy_check_mark:
io_uring_rsrc_register	RsrcRegister		:heavy_check_mark:
io_uring_rsrc_update	RsrcUpdate		:heavy_check_mark:
io_uring_rsrc_update2	RsrcUpdate2		:heavy_check_mark:
io_uring_probe_op	ProbeOp		:heavy_check_mark:
io_uring_probe	Probe		:heavy_check_mark:
io_uring_restriction	Restriction		:heavy_check_mark:
io_uring_buf	BufAndRing		:heavy_check_mark:
io_uring_buf_ring	BufAndRing		:heavy_check_mark:
io_uring_buf_reg	BufReg		:heavy_check_mark:
io_uring_getevents_arg	GetEventsArg		:heavy_check_mark:
io_uring_sync_cancel_reg	SyncCancelReg		:heavy_check_mark:
io_uring_file_index_range	FileIndexRange		:heavy_check_mark:
io_uring_recvmsg_out	RecvmsgOut		:heavy_check_mark:

(back to top)

Implemented methods

liburing name	Receiver type	Golang liburing port name	Notes	Implemented
IO_URING_CHECK_VERSION
IO_URING_VERSION_MAJOR
IO_URING_VERSION_MINOR
io_uring_buf_ring_add	BufAndRing	BufRingAdd		:heavy_check_mark:
io_uring_buf_ring_advance	BufAndRing	BufRingAdvance		:heavy_check_mark:
io_uring_buf_ring_cq_advance	Ring	BufRingCQAdvance		:heavy_check_mark:
io_uring_buf_ring_init	BufAndRing	BufRingInit		:heavy_check_mark:
io_uring_buf_ring_mask		BufRingMask		:heavy_check_mark:
io_uring_check_version		CheckVersion		:heavy_check_mark:
io_uring_close_ring_fd	Ring	CloseRingFd		:heavy_check_mark:
io_uring_cq_advance	Ring	CQAdvance		:heavy_check_mark:
io_uring_cq_has_overflow	Ring	CQHasOverflow		:heavy_check_mark:
io_uring_cq_ready	Ring	CQReady		:heavy_check_mark:
io_uring_cqe_get_data	CompletionQueueEvent	GetData		:heavy_check_mark:
io_uring_cqe_get_data64	CompletionQueueEvent	GetData64		:heavy_check_mark:
io_uring_cqe_seen	Ring	CQESeen		:heavy_check_mark:
io_uring_enter	Ring	Enter		:heavy_check_mark:
io_uring_enter2	Ring	Enter2		:heavy_check_mark:
io_uring_for_each_cqe	Ring	ForEachCQE		:heavy_check_mark:
io_uring_free_buf_ring	Ring	FreeBufRing		:heavy_check_mark:
io_uring_free_probe			:heavy_exclamation_mark:unnecessary	:heavy_multiplication_x:
io_uring_get_events	Ring	GetEvents		:heavy_check_mark:
io_uring_get_probe		GetProbe		:heavy_check_mark:
io_uring_get_probe_ring	Ring	GetProbeRing		:heavy_check_mark:
io_uring_get_sqe	Ring	GetSQE		:heavy_check_mark:
io_uring_major_version		MajorVersion		:heavy_check_mark:
io_uring_minor_version		MinorVersion		:heavy_check_mark:
io_uring_opcode_supported	Probe	IsSupported		:heavy_check_mark:
io_uring_peek_cqe	Ring	PeekCQE		:heavy_check_mark:
io_uring_prep_accept	SubmissionQueueEntry	PrepareAccept		:heavy_check_mark:
io_uring_prep_accept_direct	SubmissionQueueEntry	PrepareAcceptDirect		:heavy_check_mark:
io_uring_prep_cancel	SubmissionQueueEntry	PrepareCancel		:heavy_check_mark:
io_uring_prep_cancel64	SubmissionQueueEntry	PrepareCancel64		:heavy_check_mark:
io_uring_prep_close	SubmissionQueueEntry	PrepareClose		:heavy_check_mark:
io_uring_prep_close_direct	SubmissionQueueEntry	PrepareCloseDirect		:heavy_check_mark:
io_uring_prep_connect	SubmissionQueueEntry	PrepareConnect		:heavy_check_mark:
io_uring_prep_fadvise	SubmissionQueueEntry	PrepareFadvise		:heavy_check_mark:
io_uring_prep_fallocate	SubmissionQueueEntry	PrepareFallocate		:heavy_check_mark:
io_uring_prep_fgetxattr	SubmissionQueueEntry	PrepareFgetxattr		:heavy_check_mark:
io_uring_prep_files_update	SubmissionQueueEntry	PrepareFilesUpdate		:heavy_check_mark:
io_uring_prep_fsetxattr	SubmissionQueueEntry	PrepareFsetxattr		:heavy_check_mark:
io_uring_prep_fsync	SubmissionQueueEntry	PrepareFsync		:heavy_check_mark:
io_uring_prep_getxattr	SubmissionQueueEntry	PrepareGetxattr		:heavy_check_mark:
io_uring_prep_link	SubmissionQueueEntry	PrepareLink		:heavy_check_mark:
io_uring_prep_link_timeout	SubmissionQueueEntry	PrepareLinkTimeout		:heavy_check_mark:
io_uring_prep_linkat	SubmissionQueueEntry	PrepareLinkat		:heavy_check_mark:
io_uring_prep_madvise	SubmissionQueueEntry	PrepareMadvise		:heavy_check_mark:
io_uring_prep_mkdir	SubmissionQueueEntry	PrepareMkdir		:heavy_check_mark:
io_uring_prep_mkdirat	SubmissionQueueEntry	PrepareMkdirat		:heavy_check_mark:
io_uring_prep_msg_ring	SubmissionQueueEntry	PrepareMsgRing		:heavy_check_mark:
io_uring_prep_msg_ring_cqe_flags	SubmissionQueueEntry	PrepareMsgRingCqeFlags		:heavy_check_mark:
io_uring_prep_msg_ring_fd	SubmissionQueueEntry	PrepareMsgRingFd		:heavy_check_mark:
io_uring_prep_msg_ring_fd_alloc	SubmissionQueueEntry	PrepareMsgRingFdAlloc		:heavy_check_mark:
io_uring_prep_multishot_accept	SubmissionQueueEntry	PrepareMultishotAccept		:heavy_check_mark:
io_uring_prep_multishot_accept_direct	SubmissionQueueEntry	PrepareMultishotAcceptDirect		:heavy_check_mark:
io_uring_prep_nop	SubmissionQueueEntry	PrepareNop		:heavy_check_mark:
io_uring_prep_openat	SubmissionQueueEntry	PrepareOpenat		:heavy_check_mark:
io_uring_prep_openat2	SubmissionQueueEntry	PrepareOpenat2		:heavy_check_mark:
io_uring_prep_openat2_direct	SubmissionQueueEntry	PrepareOpenat2Direct		:heavy_check_mark:
io_uring_prep_openat_direct	SubmissionQueueEntry	PrepareOpenatDirect		:heavy_check_mark:
io_uring_prep_poll_add	SubmissionQueueEntry	PreparePollAdd		:heavy_check_mark:
io_uring_prep_poll_multishot	SubmissionQueueEntry	PreparePollMultishot		:heavy_check_mark:
io_uring_prep_poll_remove	SubmissionQueueEntry	PreparePollRemove		:heavy_check_mark:
io_uring_prep_poll_update	SubmissionQueueEntry	PreparePollUpdate		:heavy_check_mark:
io_uring_prep_provide_buffers	SubmissionQueueEntry	PrepareProvideBuffers		:heavy_check_mark:
io_uring_prep_read	SubmissionQueueEntry	PrepareRead		:heavy_check_mark:
io_uring_prep_read_fixed	SubmissionQueueEntry	PrepareReadFixed		:heavy_check_mark:
io_uring_prep_readv	SubmissionQueueEntry	PrepareReadv		:heavy_check_mark:
io_uring_prep_readv2	SubmissionQueueEntry	PrepareReadv2		:heavy_check_mark:
io_uring_prep_recv	SubmissionQueueEntry	PrepareRecv		:heavy_check_mark:
io_uring_prep_recv_multishot	SubmissionQueueEntry	PrepareRecvMultishot		:heavy_check_mark:
io_uring_prep_recvmsg	SubmissionQueueEntry	PrepareRecvMsg		:heavy_check_mark:
io_uring_prep_recvmsg_multishot	SubmissionQueueEntry	PrepareRecvMsgMultishot		:heavy_check_mark:
io_uring_prep_remove_buffers	SubmissionQueueEntry	PrepareRemoveBuffers		:heavy_check_mark:
io_uring_prep_rename	SubmissionQueueEntry	PrepareRename		:heavy_check_mark:
io_uring_prep_renameat	SubmissionQueueEntry	PrepareRenameat		:heavy_check_mark:
io_uring_prep_send	SubmissionQueueEntry	PrepareSend		:heavy_check_mark:
io_uring_prep_send_set_addr	SubmissionQueueEntry	PrepareSendSetAddr		:heavy_check_mark:
io_uring_prep_send_zc	SubmissionQueueEntry	PrepareSendZC		:heavy_check_mark:
io_uring_prep_send_zc_fixed	SubmissionQueueEntry	PrepareSendZCFixed		:heavy_check_mark:
io_uring_prep_sendmsg	SubmissionQueueEntry	PrepareSendMsg		:heavy_check_mark:
io_uring_prep_sendmsg_zc	SubmissionQueueEntry	PrepareSendmsgZC		:heavy_check_mark:
io_uring_prep_sendto	SubmissionQueueEntry	PrepareSendto		:heavy_check_mark:
io_uring_prep_setxattr	SubmissionQueueEntry	PrepareSetxattr		:heavy_check_mark:
io_uring_prep_shutdown	SubmissionQueueEntry	PrepareShutdown		:heavy_check_mark:
io_uring_prep_socket	SubmissionQueueEntry	PrepareSocket		:heavy_check_mark:
io_uring_prep_socket_direct	SubmissionQueueEntry	PrepareSocketDirect		:heavy_check_mark:
io_uring_prep_socket_direct_alloc	SubmissionQueueEntry	PrepareSocketDirectAlloc		:heavy_check_mark:
io_uring_prep_splice	SubmissionQueueEntry	PrepareSplice		:heavy_check_mark:
io_uring_prep_statx	SubmissionQueueEntry	PrepareStatx		:heavy_check_mark:
io_uring_prep_symlink	SubmissionQueueEntry	PrepareSymlink		:heavy_check_mark:
io_uring_prep_symlinkat	SubmissionQueueEntry	PrepareSymlinkat		:heavy_check_mark:
io_uring_prep_sync_file_range	SubmissionQueueEntry	PrepareSyncFileRange		:heavy_check_mark:
io_uring_prep_tee	SubmissionQueueEntry	PrepareTee		:heavy_check_mark:
io_uring_prep_timeout	SubmissionQueueEntry	PrepareTimeout		:heavy_check_mark:
io_uring_prep_timeout_remove	SubmissionQueueEntry	PrepareTimeoutRemove		:heavy_check_mark:
io_uring_prep_timeout_update	SubmissionQueueEntry	PrepareTimeoutUpdate		:heavy_check_mark:
io_uring_prep_unlink	SubmissionQueueEntry	PrepareUnlink		:heavy_check_mark:
io_uring_prep_unlinkat	SubmissionQueueEntry	PrepareUnlinkat		:heavy_check_mark:
io_uring_prep_write	SubmissionQueueEntry	PrepareWrite		:heavy_check_mark:
io_uring_prep_write_fixed	SubmissionQueueEntry	PrepareWriteFixed		:heavy_check_mark:
io_uring_prep_writev	SubmissionQueueEntry	PrepareWritev		:heavy_check_mark:
io_uring_prep_writev2	SubmissionQueueEntry	PrepareWritev2		:heavy_check_mark:
io_uring_queue_exit	Ring	QueueExit		:heavy_check_mark:
io_uring_queue_init	Ring	QueueInit		:heavy_check_mark:
io_uring_queue_init_params	Ring	QueueInitParams		:heavy_check_mark:
io_uring_recvmsg_cmsg_firsthdr	RecvmsgOut	CmsgFirsthdr		:heavy_check_mark:
io_uring_recvmsg_cmsg_nexthdr	RecvmsgOut	CmsgNexthdr		:heavy_check_mark:
io_uring_recvmsg_name	RecvmsgOut	Name		:heavy_check_mark:
io_uring_recvmsg_payload	RecvmsgOut	Payload		:heavy_check_mark:
io_uring_recvmsg_payload_length	RecvmsgOut	PayloadLength		:heavy_check_mark:
io_uring_recvmsg_validate	RecvmsgOut	RecvmsgValidate		:heavy_check_mark:
io_uring_register	Ring	Register		:heavy_check_mark:
io_uring_register_buf_ring	Ring	RegisterBufferRing		:heavy_check_mark:
io_uring_register_buffers	Ring	RegisterBuffers		:heavy_check_mark:
io_uring_register_buffers_sparse	Ring	RegisterBuffersSparse		:heavy_check_mark:
io_uring_register_buffers_tags	Ring	RegisterBuffersTags		:heavy_check_mark:
io_uring_register_buffers_update_tag	Ring	RegisterBuffersUpdateTag		:heavy_check_mark:
io_uring_register_eventfd	Ring	RegisterEventFd		:heavy_check_mark:
io_uring_register_eventfd_async	Ring	RegisterEventFdAsync		:heavy_check_mark:
io_uring_register_file_alloc_range	Ring	RegisterFileAllocRange		:heavy_check_mark:
io_uring_register_files	Ring	RegisterFiles		:heavy_check_mark:
io_uring_register_files_sparse	Ring	RegisterFilesSparse		:heavy_check_mark:
io_uring_register_files_tags	Ring	RegisterFilesTags		:heavy_check_mark:
io_uring_register_files_update	Ring	RegisterFilesUpdate		:heavy_check_mark:
io_uring_register_files_update_tag	Ring	RegisterFilesUpdateTag		:heavy_check_mark:
io_uring_register_iowq_aff	Ring	RegisterIOWQAff		:heavy_check_mark:
io_uring_register_iowq_max_workers	Ring	RegisterIOWQMaxWorkers		:heavy_check_mark:
io_uring_register_ring_fd	Ring	RegisterRingFd		:heavy_check_mark:
io_uring_register_sync_cancel	Ring	RegisterSyncCancel		:heavy_check_mark:
io_uring_setup		Setup		:heavy_check_mark:
io_uring_setup_buf_ring	Ring	SetupBufRing		:heavy_check_mark:
io_uring_sq_ready	Ring	SQReady		:heavy_check_mark:
io_uring_sq_space_left	Ring	SQSpaceLeft		:heavy_check_mark:
io_uring_sqe_set_data	SubmissionQueueEntry	SetData		:heavy_check_mark:
io_uring_sqe_set_data64	SubmissionQueueEntry	SetData64		:heavy_check_mark:
io_uring_sqe_set_flags	SubmissionQueueEntry	SetFlags		:heavy_check_mark:
io_uring_sqring_wait	Ring	SQRingWait		:heavy_check_mark:
io_uring_submit	Ring	Submit		:heavy_check_mark:
io_uring_submit_and_get_events	Ring	SubmitAndGetEvents		:heavy_check_mark:
io_uring_submit_and_wait	Ring	SubmitAndWait		:heavy_check_mark:
io_uring_submit_and_wait_timeout	Ring	SubmitAndWaitTimeout		:heavy_check_mark:
io_uring_unregister_buf_ring	Ring	UnregisterBufferRing		:heavy_check_mark:
io_uring_unregister_buffers	Ring	UnregisterBuffers		:heavy_check_mark:
io_uring_unregister_eventfd	Ring	UnregisterEventFd		:heavy_check_mark:
io_uring_unregister_files	Ring	UnregisterFiles		:heavy_check_mark:
io_uring_unregister_iowq_aff	Ring	UnregisterIOWQAff		:heavy_check_mark:
io_uring_unregister_ring_fd	Ring	UnregisterRingFd		:heavy_check_mark:
io_uring_wait_cqe	Ring	WaitCQE		:heavy_check_mark:
io_uring_wait_cqe_nr	Ring	WaitCQENr		:heavy_check_mark:
io_uring_wait_cqe_timeout	Ring	WaitCQETimeout		:heavy_check_mark:
io_uring_wait_cqes	Ring	WaitCQEs		:heavy_check_mark:

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Paweł Gaczyński - LinkedIn

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)