source: trunk/libtransmission/bandwidth.h @ 7419

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

(trunk libT) really fuck up the peer i/o code. also this breaks the mac build until someone removes iobuf.c from libtransmission's list of files.

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