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

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

(1.4x libT) backport handshake, peer, bandwidth, peer-io to 1.4x.

File size: 6.7 KB
Line 
1/*
2 * This file Copyright (C) 2008 Charles Kerr <charles@transmissionbt.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 */
61
62typedef struct tr_bandwidth tr_bandwidth;
63
64struct tr_peerIo;
65
66/**
67***
68**/
69
70/** @brief create a new tr_bandwidth object */
71tr_bandwidth*
72         tr_bandwidthNew              ( tr_session          * session,
73                                        tr_bandwidth        * parent );
74
75/** @brief destroy a tr_bandwidth object */
76void     tr_bandwidthFree             ( tr_bandwidth        * bandwidth );
77
78/** @brief test to see if the pointer refers to a live bandwidth object */
79tr_bool  tr_isBandwidth               ( const tr_bandwidth  * bandwidth );
80
81/******
82*******
83******/
84
85/**
86 * @brief Set the desired speed (in KiB/s) for this bandwidth subtree.
87 * @see tr_bandwidthAllocate
88 * @see tr_bandwidthGetDesiredSpeed
89 */
90void    tr_bandwidthSetDesiredSpeed   ( tr_bandwidth        * bandwidth,
91                                        tr_direction          direction,
92                                        double                desiredSpeed );
93
94/**
95 * @brief Get the desired speed (in KiB/s) for ths bandwidth subtree.
96 * @see tr_bandwidthSetDesiredSpeed
97 */
98double  tr_bandwidthGetDesiredSpeed   ( const tr_bandwidth  * bandwidth,
99                                        tr_direction          direction );
100
101/**
102 * @brief Set whether or not this bandwidth should throttle its iobufs' speeds
103 */
104void    tr_bandwidthSetLimited        ( tr_bandwidth        * bandwidth,
105                                        tr_direction          direction,
106                                        tr_bool               isLimited );
107
108/**
109 * @return nonzero if this bandwidth throttles its iobufs' speeds
110 */
111tr_bool tr_bandwidthIsLimited         ( const tr_bandwidth  * bandwidth,
112                                        tr_direction          direction );
113
114/**
115 * @brief allocate the next period_msec's worth of bandwidth for the iobufs to consume
116 */
117void    tr_bandwidthAllocate          ( tr_bandwidth        * bandwidth,
118                                        tr_direction          direction,
119                                        int                   period_msec );
120
121/**
122 * @brief clamps byteCount down to a number that this bandwidth will allow to be consumed
123 */
124size_t  tr_bandwidthClamp             ( const tr_bandwidth  * bandwidth,
125                                        tr_direction          direction,
126                                        size_t                byteCount );
127
128/******
129*******
130******/
131
132/**
133 * @brief Get the raw total of bytes read or sent by this bandwidth subtree.
134 */
135double  tr_bandwidthGetRawSpeed       ( const tr_bandwidth  * bandwidth,
136                                        tr_direction          direction );
137
138/**
139 * @brief Get the number of piece data bytes read or sent by this bandwidth subtree.
140 */
141double  tr_bandwidthGetPieceSpeed     ( const tr_bandwidth  * bandwidth,
142                                        tr_direction          direction );
143
144/**
145 * @brief Notify the bandwidth object that some of its allocated bandwidth has been consumed.
146 * This is is usually invoked by the iobuf after a read or write.
147 */
148void    tr_bandwidthUsed              ( tr_bandwidth        * bandwidth,
149                                        tr_direction          direction,
150                                        size_t                byteCount,
151                                        tr_bool               isPieceData );
152
153/******
154*******
155******/
156
157void    tr_bandwidthSetParent         ( tr_bandwidth        * bandwidth,
158                                        tr_bandwidth        * parent );
159
160/**
161 * Almost all the time we do want to honor a parents' bandwidth cap, so that
162 * (for example) a peer is constrained by a per-torrent cap and the global cap.
163 * But when we set a torrent's speed mode to TR_SPEEDLIMIT_UNLIMITED, then
164 * in that particular case we want to ignore the global speed limit...
165 */
166void    tr_bandwidthHonorParentLimits ( tr_bandwidth        * bandwidth,
167                                        tr_direction          direction,
168                                        tr_bool               isEnabled );
169
170/******
171*******
172******/
173
174/**
175 * @brief add a tr_peerIo to this bandwidth's list.
176 * They will be notified when more bandwidth is made available for them to consume.
177 */
178void    tr_bandwidthAddPeer           ( tr_bandwidth        * bandwidth,
179                                        struct tr_peerIo    * peerIo );
180
181/**
182 * @brief remove an iobuf from this bandwidth's list of iobufs.
183 */
184void    tr_bandwidthRemovePeer        ( tr_bandwidth        * bandwidth,
185                                        struct tr_peerIo    * peerIo );
186
187#endif
Note: See TracBrowser for help on using the repository browser.