← Back to branch summary

~ubuntu-branches/ubuntu/raring/virtualbox-ose/raring

« back to all changes in this revision

Viewing changes to include/iprt/circbuf.h

  • Committer: Bazaar Package Importer
  • Author(s): Felix Geyer
  • Date: 2011-01-30 23:27:25 UTC
  • mfrom: (0.3.12 upstream)
  • Revision ID: james.westby@ubuntu.com-20110130232725-2ouajjd2ggdet0zd
Tags: 4.0.2-dfsg-1ubuntu1
* Merge from Debian unstable, remaining changes:
  - Add Apport hook.
    - debian/virtualbox-ose.files/source_virtualbox-ose.py
    - debian/virtualbox-ose.install
  - Drop *-source packages.
* Drop ubuntu-01-fix-build-gcc45.patch, fixed upstream.
* Drop ubuntu-02-as-needed.patch, added to the Debian package.

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/iprt/circbuf.h
 
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
 
 
42
RT_C_DECLS_BEGIN
 
43
 
 
44
typedef 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 */
 
58
typedef 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
 */
 
68
RTDECL(int) RTCircBufCreate(PRTCIRCBUF *ppBuf, size_t cbSize);
 
69
 
 
70
/**
 
71
 * Destroy the circular buffer.
 
72
 *
 
73
 * @param   pBuf           The buffer to destroy.
 
74
 */
 
75
RTDECL(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
 */
 
85
RTDECL(void) RTCircBufReset(PRTCIRCBUF pBuf);
 
86
 
 
87
/**
 
88
 * Returns the current free space of the buffer.
 
89
 *
 
90
 * @param   pBuf           The buffer to query.
 
91
 */
 
92
RTDECL(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
 */
 
99
RTDECL(size_t) RTCircBufUsed(PRTCIRCBUF pBuf);
 
100
 
 
101
/**
 
102
 * Returns the size of the buffer.
 
103
 *
 
104
 * @param   pBuf           The buffer to query.
 
105
 */
 
106
RTDECL(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
 */
 
116
RTDECL(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
 */
 
124
RTDECL(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
 */
 
134
RTDECL(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
 */
 
142
RTDECL(void) RTCircBufReleaseWriteBlock(PRTCIRCBUF pBuf, size_t cbSize);
 
143
 
 
144
RT_C_DECLS_END
 
145
 
 
146
/** @} */
 
147
 
 
148
#endif /* ___iprt_circbuf_h */
 
149