circbuf.h revision 078edd33e3a22f968a7aee5a9e042bca314c2f03
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * IPRT - Lock Free Circular Buffer
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Copyright (C) 2010 Oracle Corporation
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 * 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 * 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/** @defgroup grp_rt_circbuf RTCircBuf - Lock Free Circular Buffer
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @ingroup grp_rt
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.
078edd33e3a22f968a7aee5a9e042bca314c2f03vboxsync/** @todo r=bird: this is missing docs and magic. uXPos should be offX.
078edd33e3a22f968a7aee5a9e042bca314c2f03vboxsync * cbBufSize should be cbBuf. */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsynctypedef struct RTCIRCBUF
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync /** The current read position in the buffer. */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync /** The current write position in the buffer. */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync /** How much space of the buffer is currently in use. */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync /** How big is the buffer. */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync /** The buffer itself. */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync/* Pointer to a circular buffer structure */
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Create a circular buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @returns IPRT status code.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param ppBuf Where to store the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param cbSize The size of the new buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(int) RTCircBufCreate(PRTCIRCBUF *ppBuf, size_t cbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Destroy the circular buffer.
078edd33e3a22f968a7aee5a9e042bca314c2f03vboxsync * @param pBuf The buffer to destroy. NULL is ignored.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Reset all position information in the circular buffer.
43e4d3b7a2a08b95b9e6a91abf08c6fb89ff0f51vboxsync * @note This function is not multi threading aware.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param pBuf The buffer to reset.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Returns the current free space of the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param pBuf The buffer to query.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Returns the current used space of the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param pBuf The buffer to query.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Returns the size of the buffer.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param pBuf The buffer to query.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Acquire a block of the circular buffer for reading.
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.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufAcquireReadBlock(PRTCIRCBUF pBuf, size_t cbReqSize, void **ppvStart, size_t *pcbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Release a block which was acquired by RTCircBufAcquireReadBlock.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param pBuf The buffer to acquire from.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param cbSize The size of the block.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufReleaseReadBlock(PRTCIRCBUF pBuf, size_t cbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Acquire a block of the circular buffer for writing.
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.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufAcquireWriteBlock(PRTCIRCBUF pBuf, size_t cbReqSize, void **ppvStart, size_t *pcbSize);
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * Release a block which was acquired by RTCircBufAcquireWriteBlock.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param pBuf The buffer to acquire from.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsync * @param cbSize The size of the block.
97f795f0be0c10aae9b31cc8f8d5cdf8ea2ab421vboxsyncRTDECL(void) RTCircBufReleaseWriteBlock(PRTCIRCBUF pBuf, size_t cbSize);
078edd33e3a22f968a7aee5a9e042bca314c2f03vboxsync#endif /* !___iprt_circbuf_h */