source: trunk/libtransmission/bandwidth.h @ 7576

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

(trunk libT) add "inline" hint to several one-liner functions

  • Property svn:keywords set to Date Rev Author Id
File size: 6.9 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: bandwidth.h 7576 2009-01-02 06:28:22Z charles $
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
20/**
21 * Bandwidth is an object for measuring and constraining bandwidth speeds.
22 *
23 * Bandwidth objects can be "stacked" so that a peer can be made to obey
24 * multiple constraints (for example, obeying the global speed limit and a
25 * per-torrent speed limit).
26 *
27 * HIERARCHY
28 *
29 *   Transmission's bandwidth hierarchy is a tree.
30 *   At the top is the global bandwidth object owned by tr_session.
31 *   Its children are per-torrent bandwidth objects owned by tr_torrent.
32 *   Underneath those are per-peer bandwidth objects owned by tr_peer.
33 *
34 *   tr_session also owns a tr_handshake's bandwidths, so that the handshake
35 *   I/O can be counted in the global raw totals.  When the handshake is done,
36 *   the bandwidth's ownership passes to a tr_peer.
37 *
38 * MEASURING
39 *
40 *   When you ask a bandwidth object for its speed, it gives the speed of the
41 *   subtree underneath it as well.  So you can get Transmission's overall
42 *   speed by quering tr_session's bandwidth, per-torrent speeds by asking
43 *   tr_torrent's bandwidth, and per-peer speeds by asking tr_peer's bandwidth.
44 *
45 * CONSTRAINING
46 *
47 *   Call tr_bandwidthAllocate() periodically.  tr_bandwidth knows its current
48 *   speed and will decide how many bytes to make available over the
49 *   user-specified period to reach the user-specified desired speed.
50 *   If appropriate, it notifies its peer-ios that new bandwidth is available.
51 *
52 *   tr_bandwidthAllocate() operates on the tr_bandwidth subtree, so usually
53 *   you'll only need to invoke it for the top-level tr_session bandwidth.
54 *
55 *   The peer-ios all have a pointer to their associated tr_bandwidth object,
56 *   and call tr_bandwidthClamp() before performing I/O to see how much
57 *   bandwidth they can safely use.
58 */
59
60typedef struct tr_bandwidth tr_bandwidth;
61
62struct tr_peerIo;
63
64/**
65***
66**/
67
68/** @brief create a new tr_bandwidth object */
69tr_bandwidth*
70         tr_bandwidthNew              ( tr_session          * session,
71                                        tr_bandwidth        * parent );
72
73/** @brief destroy a tr_bandwidth object */
74void     tr_bandwidthFree             ( tr_bandwidth        * bandwidth );
75
76/** @brief test to see if the pointer refers to a live bandwidth object */
77extern inline tr_bool
78         tr_isBandwidth               ( const tr_bandwidth  * bandwidth );
79
80/******
81*******
82******/
83
84/**
85 * @brief Set the desired speed (in KiB/s) for this bandwidth subtree.
86 * @see tr_bandwidthAllocate
87 * @see tr_bandwidthGetDesiredSpeed
88 */
89extern inline void
90        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 */
98extern inline double
99        tr_bandwidthGetDesiredSpeed   ( const tr_bandwidth  * bandwidth,
100                                        tr_direction          direction );
101
102/**
103 * @brief Set whether or not this bandwidth should throttle its peer-io's speeds
104 */
105extern inline void
106        tr_bandwidthSetLimited        ( tr_bandwidth        * bandwidth,
107                                        tr_direction          direction,
108                                        tr_bool               isLimited );
109
110/**
111 * @return nonzero if this bandwidth throttles its peer-ios speeds
112 */
113extern inline tr_bool
114        tr_bandwidthIsLimited         ( const tr_bandwidth  * bandwidth,
115                                        tr_direction          direction );
116
117/**
118 * @brief allocate the next period_msec's worth of bandwidth for the peer-ios to consume
119 */
120void    tr_bandwidthAllocate          ( tr_bandwidth        * bandwidth,
121                                        tr_direction          direction,
122                                        int                   period_msec );
123
124/**
125 * @brief clamps byteCount down to a number that this bandwidth will allow to be consumed
126 */
127size_t  tr_bandwidthClamp             ( const tr_bandwidth  * bandwidth,
128                                        tr_direction          direction,
129                                        size_t                byteCount );
130
131/******
132*******
133******/
134
135/**
136 * @brief Get the raw total of bytes read or sent by this bandwidth subtree.
137 */
138extern inline double
139        tr_bandwidthGetRawSpeed       ( const tr_bandwidth  * bandwidth,
140                                        tr_direction          direction );
141
142/**
143 * @brief Get the number of piece data bytes read or sent by this bandwidth subtree.
144 */
145extern inline double
146        tr_bandwidthGetPieceSpeed     ( const tr_bandwidth  * bandwidth,
147                                        tr_direction          direction );
148
149/**
150 * @brief Notify the bandwidth object that some of its allocated bandwidth has been consumed.
151 * This is is usually invoked by the peer-io after a read or write.
152 */
153void    tr_bandwidthUsed              ( tr_bandwidth        * bandwidth,
154                                        tr_direction          direction,
155                                        size_t                byteCount,
156                                        tr_bool               isPieceData );
157
158/******
159*******
160******/
161
162void    tr_bandwidthSetParent         ( tr_bandwidth        * bandwidth,
163                                        tr_bandwidth        * parent );
164
165/**
166 * Almost all the time we do want to honor a parents' bandwidth cap, so that
167 * (for example) a peer is constrained by a per-torrent cap and the global cap.
168 * But when we set a torrent's speed mode to TR_SPEEDLIMIT_UNLIMITED, then
169 * in that particular case we want to ignore the global speed limit...
170 */
171void    tr_bandwidthHonorParentLimits ( tr_bandwidth        * bandwidth,
172                                        tr_direction          direction,
173                                        tr_bool               isEnabled );
174
175/******
176*******
177******/
178
179/**
180 * @brief add a tr_peerIo to this bandwidth's list.
181 * They will be notified when more bandwidth is made available for them to consume.
182 */
183extern inline void
184        tr_bandwidthAddPeer           ( tr_bandwidth        * bandwidth,
185                                        struct tr_peerIo    * peerIo );
186
187/**
188 * @brief remove a peer-io from this bandwidth's list.
189 */
190extern inline void
191        tr_bandwidthRemovePeer        ( tr_bandwidth        * bandwidth,
192                                        struct tr_peerIo    * peerIo );
193
194#endif
Note: See TracBrowser for help on using the repository browser.