Documentation
¶
Index ¶
Constants ¶
const ( // UnlimitedBudget is a special value for the budget that means the timer has no budget UnlimitedBudget = time.Duration(math.MaxInt64) // DynamicBudget is a special value for the budget that means the timer should inherit the budget from its parent // It is the default value if no options such as WithBudget, WithUnlimitedBudget or WithInheritedBudget are provided DynamicBudget = ^time.Duration(0) )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DynamicBudgetFunc ¶
DynamicBudgetFunc is a function that is called on all children when a change to the parent happens
type NodeTimer ¶
type NodeTimer interface {
Timer
SumTimer
// NewNode creates a new NodeTimer with the given name and options. The given name must match one of the component name of the parent timer.
// A node timer is required to have at least one component. If no component is provided, it will return an error asking you to use NewLeaf instead.
// If no budget is provided, it will inherit the budget from its parent when calling Start().
// NewNode is thread-safe
NewNode(name string, options ...Option) (NodeTimer, error)
// NewLeaf creates a new Timer with the given name and options. The given name must match one of the component name of the parent timer.
// A leaf timer is forbidden to have components. If a component is provided, it will return an error asking you to use NewNode instead.
// If no budget is provided, it will inherit the budget from its parent when calling Start().
// NewLeaf is thread-safe
NewLeaf(name string, options ...Option) (Timer, error)
// MustLeaf creates a new Timer with the given name and options. The given name must match one of the component name of the parent timer.
// MustLeaf wraps a call to NewLeaf but will panic if the error is not nil.
// MustLeaf is thread-safe
MustLeaf(name string, options ...Option) Timer
// AddTime adds the given duration to the component of the timer with the given name.
// AddTime is thread-safe
AddTime(name string, duration time.Duration)
// Stats returns a map of the time spent in each component of the timer.
// Stats is thread-safe
Stats() map[string]time.Duration
// contains filtered or unexported methods
}
NodeTimer is the interface for tree timers. NewTreeTimer will provide you with a NodeTimer. NodeTimer can have children (NodeTimer or Timer) and will compute the sum of their spent time each time a children timer calls its Stop() method. To add children to a NodeTimer, you have to specify component names when creating the timer with the WithComponent and WithComponents options. The component names must be unique and cannot be empty. The component names are used to identify the children timers. The returned timer can now create children timers using the NewNode and NewLeaf functions using the names provided when creating the parent timer. Multiple timers from the same component can be used in parallel and will be summed together. In parallel to that, NodeTimer can have their own wall time timer and budget that will apply to the sum of their children and their own timer. The following functions are the same as the Timer interface but works using the sum of the children timers: - SumSpent() -> Spent() - SumRemaining() -> Remaining() - SumExhausted() -> Exhausted() Keep in mind that the timer itself (only Start and Stop) is NOT thread-safe and once Stop() is called, the NodeTimer cannot be restarted.
func NewTreeTimer ¶
NewTreeTimer creates a new Timer with the given options. You have to specify either the option WithBudget or WithUnlimitedBudget and at least one component using the WithComponents option.
type Option ¶
type Option func(*config)
Option are the configuration options for any type of timer. Please read the documentation of said timer to see which options are available
func WithBudget ¶
WithBudget is an Option that sets the budget value
func WithComponents ¶
WithComponents is an Option that adds multiple components to the components list
func WithInheritedBudget ¶
func WithInheritedBudget() Option
WithInheritedBudget is an Option that sets the DynamicBudget flag on config.budget
func WithInheritedSumBudget ¶
func WithInheritedSumBudget() Option
WithInheritedSumBudget is an Option that sets the DynamicBudget flag on config.budget and sets the DynamicBudgetFunc to sum the remaining time of all children
func WithUnlimitedBudget ¶
func WithUnlimitedBudget() Option
WithUnlimitedBudget is an Option that sets the UnlimitedBudget flag on config.budget
type SumTimer ¶
type SumTimer interface {
// SumSpent returns the sum of the time spent in each component of the timer.
// SumSpent is thread-safe
SumSpent() time.Duration
// SumRemaining returns the sum of the time remaining in each component of the timer.
// SumRemaining returns UnlimitedBudget if the timer has no budget. (UnlimitedBudget)
// SumRemaining is thread-safe
SumRemaining() time.Duration
// SumExhausted returns true if the sum of the time spent in each component of the timer is greater than the budget.
// SumExhausted returns false if the timer has no budget. (UnlimitedBudget)
// SumExhausted is thread-safe
SumExhausted() bool
}
SumTimer is a sub-interface for timers capable of having children and making the sum of their time spent. NewTreeTimer will provide you with a timer supporting this interface
type Timer ¶
type Timer interface {
// Start starts the timer and returns the start time.
// If the timer was already started, it returns the previous start time.
// If the timer was started without specifying a budget, it will inherit the budget from its parent when calling Start().
// if the timer has no parent and no budget was specified, the call creating the timer (either NewTreeTimer or NewTimer) will return an error asking to specify a budget (which can be unlimited).
// Start is NOT thread-safe
Start() time.Time
// Stop ends the timer and returns the time spent on the timer as Spent() would.
// Stop will trigger the computation of sum timers if the timer is part of a tree. See NodeTimer for more information.
// Stop is NOT thread-safe
Stop() time.Duration
// Spent returns the current time spent between Start() and Stop() or between Start() and now if the timer is still running.
// Spent is thread-safe
Spent() time.Duration
// Remaining returns the time remaining before the timer reaches its budget. (budget - Spent())
// It returns 0 if the timer is exhausted. Remaining may never return a value below zero.
// Remaining only makes sense if the timer has a budget. If the timer has no budget, it returns the special value UnlimitedBudget.
// Remaining is thread-safe
Remaining() time.Duration
// Exhausted returns true if the timer spent in the timer is greater than the budget. (Spent() > budget)
// Exhausted may return true only in case the time has a budget. If the timer has n, it returns false.
// Exhausted is thread-safe
Exhausted() bool
// Timed is a convenience function that starts the timer, calls the provided function and stops the timer.
// Timed is panic-safe and will stop the timer even if the function panics.
// Timed is NOT thread-safe
Timed(timedFunc func(timer Timer)) time.Duration
}
Timer is the default interface for all timers. NewTimer will provide you with a Timer. Keep in mind that they are NOT thread-safe and once Stop() is called, the Timer cannot be restarted.
Source Files