VirtualBox

source: vbox/trunk/include/iprt/circbuf.h@ 33469

Last change on this file since 33469 was 33291, checked in by vboxsync, 14 years ago

Runtime: no colon

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 4.3 KB
Line 
1/** @file
2 * IPRT - Lock Free Circular Buffer
3 */
4
5/*
6 * Copyright (C) 2010 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_circbuf_h
27#define ___iprt_circbuf_h
28
29#include <iprt/types.h>
30
31/** @defgroup grp_rt_circbuf RTCircBuf - Lock Free Circular Buffer
32 * @ingroup grp_rt
33 *
34 * Implementation of a lock free circular buffer which could be used in a multi
35 * threaded environment. Note that only the acquire, release and getter
36 * functions are threading aware. So don't use reset if the circular buffer is
37 * still in use.
38 *
39 * @{
40 */
41
42RT_C_DECLS_BEGIN
43
44typedef struct RTCIRCBUF
45{
46 /** The current read position in the buffer. */
47 size_t uReadPos;
48 /** The current write position in the buffer. */
49 size_t uWritePos;
50 /** How much space of the buffer is currently in use. */
51 volatile size_t cbBufUsed;
52 /** How big is the buffer. */
53 size_t cbBufSize;
54 /** The buffer itself. */
55 void *pvBuf;
56} RTCIRCBUF;
57/* Pointer to a circular buffer structure */
58typedef RTCIRCBUF* PRTCIRCBUF;
59
60/**
61 * Create a circular buffer.
62 *
63 * @returns IPRT status code.
64 *
65 * @param ppBuf Where to store the buffer.
66 * @param cbSize The size of the new buffer.
67 */
68RTDECL(int) RTCircBufCreate(PRTCIRCBUF *ppBuf, size_t cbSize);
69
70/**
71 * Destroy the circular buffer.
72 *
73 * @param pBuf The buffer to destroy.
74 */
75RTDECL(void) RTCircBufDestroy(PRTCIRCBUF pBuf);
76
77
78/**
79 * Reset all position information in the circular buffer.
80 *
81 * @note This function is not multi threading aware.
82 *
83 * @param pBuf The buffer to reset.
84 */
85RTDECL(void) RTCircBufReset(PRTCIRCBUF pBuf);
86
87/**
88 * Returns the current free space of the buffer.
89 *
90 * @param pBuf The buffer to query.
91 */
92RTDECL(size_t) RTCircBufFree(PRTCIRCBUF pBuf);
93
94/**
95 * Returns the current used space of the buffer.
96 *
97 * @param pBuf The buffer to query.
98 */
99RTDECL(size_t) RTCircBufUsed(PRTCIRCBUF pBuf);
100
101/**
102 * Returns the size of the buffer.
103 *
104 * @param pBuf The buffer to query.
105 */
106RTDECL(size_t) RTCircBufSize(PRTCIRCBUF pBuf);
107
108/**
109 * Acquire a block of the circular buffer for reading.
110 *
111 * @param pBuf The buffer to acquire from.
112 * @param cbReqSize The requested size of the block.
113 * @param ppvStart The resulting memory pointer.
114 * @param pcbSize The resulting size of the memory pointer.
115 */
116RTDECL(void) RTCircBufAcquireReadBlock(PRTCIRCBUF pBuf, size_t cbReqSize, void **ppvStart, size_t *pcbSize);
117
118/**
119 * Release a block which was acquired by RTCircBufAcquireReadBlock.
120 *
121 * @param pBuf The buffer to acquire from.
122 * @param cbSize The size of the block.
123 */
124RTDECL(void) RTCircBufReleaseReadBlock(PRTCIRCBUF pBuf, size_t cbSize);
125
126/**
127 * Acquire a block of the circular buffer for writing.
128 *
129 * @param pBuf The buffer to acquire from.
130 * @param cbReqSize The requested size of the block.
131 * @param ppvStart The resulting memory pointer.
132 * @param pcbSize The resulting size of the memory pointer.
133 */
134RTDECL(void) RTCircBufAcquireWriteBlock(PRTCIRCBUF pBuf, size_t cbReqSize, void **ppvStart, size_t *pcbSize);
135
136/**
137 * Release a block which was acquired by RTCircBufAcquireWriteBlock.
138 *
139 * @param pBuf The buffer to acquire from.
140 * @param cbSize The size of the block.
141 */
142RTDECL(void) RTCircBufReleaseWriteBlock(PRTCIRCBUF pBuf, size_t cbSize);
143
144RT_C_DECLS_END
145
146/** @} */
147
148#endif /* ___iprt_circbuf_h */
149
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette