source: trunk/libtransmission/bandwidth.h @ 7154

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

(libT) yet another stab at getting bandwidth management under control. this version may suck less than previous attempts. It also breaks the mac build until someone adds iobuf.[ch] to xcode...

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.