[thirdparty/squid.git] / doc / Programming-Guide / DelayPools.dox

/*
 * Copyright (C) 1996-2021 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */

/**
\page 10_DelayPools Delay Pools

\section DelayPoolsIntro Introduction
\par
	A DelayPool is a Composite used to manage bandwidth for any request
	assigned to the pool by an access expression. DelayId's are a used
	to manage the bandwidth on a given request, whereas a DelayPool
	manages the bandwidth availability and assigned DelayId's.

\section ExtendingDelayPools Extending Delay Pools
\par
	A CompositePoolNode is the base type for all members of a DelayPool.
	Any child must implement the RefCounting primitives, as well as five
	delay pool functions:
	\li	stats() - provide cachemanager statistics for itself.
	\li	dump() - generate squid.conf syntax for the current configuration of the item.
	\li	update() - allocate more bandwidth to all buckets in the item.
	\li	parse() - accept squid.conf syntax for the item, and configure for use appropriately.
	\li	id() - return a DelayId entry for the current item.

\par
	A DelayIdComposite is the base type for all delay Id's. Concrete
	Delay Id's must implement the refcounting primitives, as well as two
	delay id functions:
	\li	bytesWanted() - return the largest amount of bytes that this delay id allows by policy.
	\li	bytesIn() - record the use of bandwidth by the request(s) that this delayId is monitoring.

\par
	Composite creation is currently under design review, so see the
	DelayPool class and follow the parse() code path for details.

\section NeatExtensions Neat things that could be done.
\par
	With the composite structure, some neat things have become possible.
	For instance:

\par	Dynamically defined pool arrangements.
	For instance an aggregate (class 1) combined with the per-class-C-net tracking of a 
	class 3 pool, without the individual host tracking. This differs
	from a class 3 pool with -1/-1 in the host bucket, because no memory
	or cpu would be used on hosts, whereas with a class 3 pool, they are
	allocated and used.

\par	Per request bandwidth limits.
	A delayId that contains it's own bucket could limit each request
	independently to a given policy, with no aggregate restrictions.

 */
Commit	Line	Data
f2a134b9	1	/*
f70aedc4	2	* Copyright (C) 1996-2021 The Squid Software Foundation and contributors
f2a134b9 AJ	3	*
	4	* Squid software is distributed under GPLv2+ license and includes
	5	* contributions from numerous individuals and organizations.
	6	* Please see the COPYING and CONTRIBUTORS files for details.
	7	*/
	8
8b651fb3	9	/**
	10	\page 10_DelayPools Delay Pools
	11
f439fbd2	12	\section DelayPoolsIntro Introduction
8b651fb3	13	\par
	14	A DelayPool is a Composite used to manage bandwidth for any request
	15	assigned to the pool by an access expression. DelayId's are a used
a4029d6d	16	to manage the bandwidth on a given request, whereas a DelayPool
8b651fb3	17	manages the bandwidth availability and assigned DelayId's.
	18
	19	\section ExtendingDelayPools Extending Delay Pools
	20	\par
	21	A CompositePoolNode is the base type for all members of a DelayPool.
	22	Any child must implement the RefCounting primitives, as well as five
	23	delay pool functions:
	24	\li stats() - provide cachemanager statistics for itself.
	25	\li dump() - generate squid.conf syntax for the current configuration of the item.
a4029d6d	26	\li update() - allocate more bandwidth to all buckets in the item.
8b651fb3	27	\li parse() - accept squid.conf syntax for the item, and configure for use appropriately.
	28	\li id() - return a DelayId entry for the current item.
	29
	30	\par
	31	A DelayIdComposite is the base type for all delay Id's. Concrete
	32	Delay Id's must implement the refcounting primitives, as well as two
	33	delay id functions:
	34	\li bytesWanted() - return the largest amount of bytes that this delay id allows by policy.
	35	\li bytesIn() - record the use of bandwidth by the request(s) that this delayId is monitoring.
	36
	37	\par
	38	Composite creation is currently under design review, so see the
	39	DelayPool class and follow the parse() code path for details.
	40
	41	\section NeatExtensions Neat things that could be done.
	42	\par
	43	With the composite structure, some neat things have become possible.
	44	For instance:
	45
	46	\par Dynamically defined pool arrangements.
	47	For instance an aggregate (class 1) combined with the per-class-C-net tracking of a
	48	class 3 pool, without the individual host tracking. This differs
	49	from a class 3 pool with -1/-1 in the host bucket, because no memory
	50	or cpu would be used on hosts, whereas with a class 3 pool, they are
	51	allocated and used.
	52
	53	\par Per request bandwidth limits.
	54	A delayId that contains it's own bucket could limit each request
	55	independently to a given policy, with no aggregate restrictions.
	56
	57	*/