include/iprt/circbuf.h

97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/** @file
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * IPRT - Lock Free Circular Buffer
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/*
c7814cf6e1240a519cbec0441e033d0e2470ed00vboxsync * Copyright (C) 2010-2011 Oracle Corporation
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * available from http://www.virtualbox.org. This file is free software;
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * you can redistribute it and/or modify it under the terms of the GNU
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * General Public License (GPL) as published by the Free Software
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * The contents of this file may alternatively be used under the terms
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * of the Common Development and Distribution License Version 1.0
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * VirtualBox OSE distribution, in which case the provisions of the
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * CDDL are applicable instead of those of the GPL.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * You may elect to license modified versions of this file under the
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * terms and conditions of either the GPL or the CDDL or both.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync#ifndef ___iprt_circbuf_h
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync#define ___iprt_circbuf_h
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync#include <iprt/types.h>
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/** @defgroup grp_rt_circbuf    RTCircBuf - Lock Free Circular Buffer
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @ingroup grp_rt
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Implementation of a lock free circular buffer which could be used in a multi
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * threaded environment. Note that only the acquire, release and getter
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * functions are threading aware. So don't use reset if the circular buffer is
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * still in use.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @{
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRT_C_DECLS_BEGIN
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
292dc462b10ba7ef37b871434e332aecf8ad97dfvboxsync/** Pointer to a circular buffer (abstract). */
292dc462b10ba7ef37b871434e332aecf8ad97dfvboxsynctypedef struct RTCIRCBUF *PRTCIRCBUF;
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Create a circular buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @returns IPRT status code.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   ppBuf          Where to store the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   cbSize         The size of the new buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(int) RTCircBufCreate(PRTCIRCBUF *ppBuf, size_t cbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Destroy the circular buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
078edd33e3a22f968a7aee5a9e042bca314c2f03vboxsync * @param   pBuf           The buffer to destroy.  NULL is ignored.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufDestroy(PRTCIRCBUF pBuf);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Reset all position information in the circular buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
43e4d3b7a2a08b95b9e6a91abf08c6fb89ff0f51vboxsync * @note This function is not multi threading aware.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to reset.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufReset(PRTCIRCBUF pBuf);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Returns the current free space of the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to query.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(size_t) RTCircBufFree(PRTCIRCBUF pBuf);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Returns the current used space of the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to query.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(size_t) RTCircBufUsed(PRTCIRCBUF pBuf);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Returns the size of the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to query.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(size_t) RTCircBufSize(PRTCIRCBUF pBuf);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
4e4a8e041182dff5c52892bee58a5d8f58f4bdadvboxsyncRTDECL(bool) RTCircBufIsReading(PRTCIRCBUF pBuf);
4e4a8e041182dff5c52892bee58a5d8f58f4bdadvboxsyncRTDECL(bool) RTCircBufIsWriting(PRTCIRCBUF pBuf);
4e4a8e041182dff5c52892bee58a5d8f58f4bdadvboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Acquire a block of the circular buffer for reading.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to acquire from.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   cbReqSize      The requested size of the block.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   ppvStart       The resulting memory pointer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pcbSize        The resulting size of the memory pointer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufAcquireReadBlock(PRTCIRCBUF pBuf, size_t cbReqSize, void **ppvStart, size_t *pcbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Release a block which was acquired by RTCircBufAcquireReadBlock.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to acquire from.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   cbSize         The size of the block.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufReleaseReadBlock(PRTCIRCBUF pBuf, size_t cbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Acquire a block of the circular buffer for writing.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to acquire from.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   cbReqSize      The requested size of the block.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   ppvStart       The resulting memory pointer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pcbSize        The resulting size of the memory pointer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufAcquireWriteBlock(PRTCIRCBUF pBuf, size_t cbReqSize, void **ppvStart, size_t *pcbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/**
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Release a block which was acquired by RTCircBufAcquireWriteBlock.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync *
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   pBuf           The buffer to acquire from.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param   cbSize         The size of the block.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufReleaseWriteBlock(PRTCIRCBUF pBuf, size_t cbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRT_C_DECLS_END
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/** @} */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync
078edd33e3a22f968a7aee5a9e042bca314c2f03vboxsync#endif /* !___iprt_circbuf_h */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync