source: branches/1.4x/libtransmission/bandwidth.h @ 7177

Last change on this file since 7177 was 7177, checked in by charles, 12 years ago

(1.4x libT) backport the bandwidth fixes back to the 1.4x branch, pass #3: add the new files bandwidth.[ch] and iobuf.[ch]
File size: 6.6 KB
Line 
1/*
2 * This file Copyright (C) 2008 Charles Kerr <charles@rebelbase.com>
3 *
4 * This file is licensed by the GPL version 2.  Works owned by the
5 * Transmission project are granted a special exemption to clause 2(b)
6 * so that the bulk of its code can remain under the MIT license.
7 * This exemption does not extend to derived works not owned by
8 * the Transmission project.
9 *
10 * $Id:$
11 */
12
13#ifndef __TRANSMISSION__
14#error only libtransmission should #include this header.
15#endif
16
17#ifndef TR_BANDWIDTH_H
18#define TR_BANDWIDTH_H
19
20struct tr_iobuf;
21
22/**
23 * Bandwidth is an object for measuring and constraining bandwidth speeds.
24 *
25 * Bandwidth objects can be "stacked" so that a peer can be made to obey
26 * multiple constraints (for example, obeying the global speed limit and a
27 * per-torrent speed limit).
28 *
29 * HIERARCHY
30 *
31 *   Transmission's bandwidth hierarchy is a tree.
32 *   At the top is the global bandwidth object owned by tr_session.
33 *   Its children are per-torrent bandwidth objects owned by tr_torrent.
34 *   Underneath those are per-peer bandwidth objects owned by tr_peer.
35 *
36 *   tr_session also owns a tr_handshake's bandwidths, so that the handshake
37 *   I/O can be counted in the global raw totals.  When the handshake is done,
38 *   the bandwidth's ownership passes to a tr_peer.
39 *
40 * MEASURING
41 *
42 *   When you ask a bandwidth object for its speed, it gives the speed of the
43 *   subtree underneath it as well.  So you can get Transmission's overall
44 *   speed by quering tr_session's bandwidth, per-torrent speeds by asking
45 *   tr_torrent's bandwidth, and per-peer speeds by asking tr_peer's bandwidth.
46 *
47 * CONSTRAINING
48 *
49 *   Call tr_bandwidthAllocate() periodically.  tr_bandwidth knows its current
50 *   speed and will decide how many bytes to make available over the
51 *   user-specified period to reach the user-specified desired speed.
52 *   If appropriate, it notifies its iobufs that new bandwidth is available.
53 *
54 *   tr_bandwidthAllocate() operates on the tr_bandwidth subtree, so usually
55 *   you'll only need to invoke it for the top-level tr_session bandwidth.
56 *
57 *   The iobufs all have a pointer to their associated tr_bandwidth object,
58 *   and call tr_bandwidthClamp() before performing I/O to see how much
59 *   bandwidth they can safely use.
60 */
61typedef struct tr_bandwidth tr_bandwidth;
62
63/**
64***
65**/
66
67/** @brief create a new tr_bandwidth object */
68tr_bandwidth*
69         tr_bandwidthNew              ( tr_session          * session,
70                                        tr_bandwidth        * parent );
71
72/** @brief destroy a tr_bandwidth object */
73void     tr_bandwidthFree             ( tr_bandwidth        * bandwidth );
74
75/******
76*******
77******/
78
79/**
80 * @brief Set the desired speed (in KiB/s) for this bandwidth subtree.
81 * @see tr_bandwidthAllocate
82 * @see tr_bandwidthGetDesiredSpeed
83 */
84void    tr_bandwidthSetDesiredSpeed   ( tr_bandwidth        * bandwidth,
85                                        tr_direction          direction,
86                                        double                desiredSpeed );
87
88/**
89 * @brief Get the desired speed (in KiB/s) for ths bandwidth subtree.
90 * @see tr_bandwidthSetDesiredSpeed
91 */
92double  tr_bandwidthGetDesiredSpeed   ( const tr_bandwidth  * bandwidth,
93                                        tr_direction          direction );
94
95/**
96 * @brief Set whether or not this bandwidth should throttle its iobufs' speeds
97 */
98void    tr_bandwidthSetLimited        ( tr_bandwidth        * bandwidth,
99                                        tr_direction          direction,
100                                        int                   isLimited );
101
102/**
103 * @return nonzero if this bandwidth throttles its iobufs' speeds
104 */
105int     tr_bandwidthIsLimited         ( const tr_bandwidth  * bandwidth,
106                                        tr_direction          direction );
107
108/**
109 * @brief allocate the next period_msec's worth of bandwidth for the iobufs to consume
110 */
111void    tr_bandwidthAllocate          ( tr_bandwidth        * bandwidth,
112                                        tr_direction          direction,
113                                        int                   period_msec );
114
115/**
116 * @brief clamps byteCount down to a number that this bandwidth will allow to be consumed
117 */
118size_t  tr_bandwidthClamp             ( const tr_bandwidth  * bandwidth,
119                                        tr_direction          direction,
120                                        size_t                byteCount );
121
122/******
123*******
124******/
125
126/**
127 * @brief Get the raw total of bytes read or sent by this bandwidth subtree.
128 */
129double  tr_bandwidthGetRawSpeed       ( const tr_bandwidth  * bandwidth,
130                                        tr_direction          direction );
131
132/**
133 * @brief Get the number of piece data bytes read or sent by this bandwidth subtree.
134 */
135double  tr_bandwidthGetPieceSpeed     ( const tr_bandwidth  * bandwidth,
136                                        tr_direction          direction );
137
138/**
139 * @brief Notify the bandwidth object that some of its allocated bandwidth has been consumed.
140 * This is is usually invoked by the iobuf after a read or write.
141 */
142void    tr_bandwidthUsed              ( tr_bandwidth        * bandwidth,
143                                        tr_direction          direction,
144                                        size_t                byteCount,
145                                        int                   isPieceData );
146
147/******
148*******
149******/
150
151void    tr_bandwidthSetParent         ( tr_bandwidth        * bandwidth,
152                                        tr_bandwidth        * parent );
153
154/**
155 * Almost all the time we do want to honor a parents' bandwidth cap, so that
156 * (for example) a peer is constrained by a per-torrent cap and the global cap.
157 * But when we set a torrent's speed mode to TR_SPEEDLIMIT_UNLIMITED, then
158 * in that particular case we want to ignore the global speed limit...
159 */
160void    tr_bandwidthHonorParentLimits ( tr_bandwidth        * bandwidth,
161                                        tr_direction          direction,
162                                        int                   isEnabled );
163
164/******
165*******
166******/
167
168/**
169 * @brief add an iobuf to this bandwidth's list of iobufs.
170 * They will be notified when more bandwidth is made available for them to consume.
171 */
172void    tr_bandwidthAddBuffer         ( tr_bandwidth        * bandwidth,
173                                        struct tr_iobuf     * iobuf );
174
175/**
176 * @brief remove an iobuf from this bandwidth's list of iobufs.
177 */
178void    tr_bandwidthRemoveBuffer      ( tr_bandwidth        * bandwidth,
179                                        struct tr_iobuf     * iobuf );
180
181#endif
Note: See TracBrowser for help on using the repository browser.