cooldown

package module
v0.0.0-...-b2e5fe7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 2, 2026 License: MIT Imports: 5 Imported by: 1

README

cooldown

A Go library implementing cooldown.

Get started
package main

import (
	"fmt"
	"sync"
	"time"

	"github.com/k4ties/cooldown"
)

func main() {
	cd := cooldown.New(cooldown.OptionHandler(new(Handler)))
	cd.Start(time.Second)
	cd.Active() // true

	<-time.After(time.Millisecond)
	cd.Renew()

	<-time.After(time.Second * 3)
	cd.Stop()
}

type Handler struct {
	cooldown.NopHandler // implements cooldown.Handler
	first               sync.Once
}

func (h *Handler) HandleStart(ctx *cooldown.Context, _ time.Duration) {
	h.first.Do(func() {
		// The event can be canceled
		ctx.Cancel()
	})
	fmt.Println("handle start")
}
func (h *Handler) HandleStop(_ *cooldown.CoolDown, cause cooldown.StopCause) {
	// This event cannot be canceled
	fmt.Printf("handle stop, cause=%v\n", cause)
}

// HandleRenew is implemented by cooldown.NopHandler

You can see more examples in /examples folder.

Credits

dragonfly

License

MIT

Documentation

Overview

Package cooldown is used to make cooldowns in go. It has basic and nonbasic implementations.

Basic is very easy designed and have no features. Unlike others: ValuedHandler and CoolDown: they're starting timer via time.AfterFunc, that cancels itself, when cooldown expires.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrStopCauseExpired used when cooldown is expired.
	ErrStopCauseExpired = errors.New("cooldown expired")
	// ErrStopCauseCancelled used when cooldown is canceled in event by user.
	ErrStopCauseCancelled = errors.New("cooldown cancelled")
)

Functions

This section is empty.

Types

type Basic 

type Basic struct {
	L sync.RWMutex
	// contains filtered or unexported fields
}

Basic represents very basic 'lazy' cooldown. You can create it simpy via new(cooldown.Basic).

func (*Basic) Active 

func (cooldown *Basic) Active() bool

Active returns true if cooldown is currently active.

func (*Basic) ActiveUnsafe 

func (cooldown *Basic) ActiveUnsafe() bool

func (*Basic) Pause 

func (cooldown *Basic) Pause() bool

Pause pauses cooldown if it is not already paused. Returns true if successfully paused.

func (*Basic) PauseUnsafe 

func (cooldown *Basic) PauseUnsafe() bool

func (*Basic) Paused 

func (cooldown *Basic) Paused() bool

Paused returns true if cooldown is paused.

func (*Basic) PausedUnsafe 

func (cooldown *Basic) PausedUnsafe() bool

func (*Basic) Remaining 

func (cooldown *Basic) Remaining() time.Duration

Remaining returns duration until cooldown expiration.

func (*Basic) RemainingUnsafe 

func (cooldown *Basic) RemainingUnsafe() time.Duration

func (*Basic) Reset 

func (cooldown *Basic) Reset()

Reset resets the cooldown state.

func (*Basic) ResetUnsafe 

func (cooldown *Basic) ResetUnsafe()

func (*Basic) Resume 

func (cooldown *Basic) Resume() bool

Resume resumes the cooldown if it is paused. Returns true if successfully resumed.

func (*Basic) ResumeUnsafe 

func (cooldown *Basic) ResumeUnsafe() bool

func (*Basic) Set 

func (cooldown *Basic) Set(dur time.Duration)

Set updates state of the cooldown. If provided duration is negative, cooldown will just reset.

func (*Basic) SetUnsafe 

func (cooldown *Basic) SetUnsafe(dur time.Duration)

func (*Basic) State 

func (cooldown *Basic) State() (res BasicState)

State returns the current state of the basic cooldown.

func (*Basic) StateUnsafe 

func (cooldown *Basic) StateUnsafe() (state BasicState)

func (*Basic) TogglePause 

func (cooldown *Basic) TogglePause() (paused bool)

TogglePause toggles the pause state of the cooldown. Returns true if cooldown was paused.

func (*Basic) TogglePauseUnsafe 

func (cooldown *Basic) TogglePauseUnsafe() (paused bool)

type BasicState 

type BasicState struct {
	// Active marks if cooldown is active.
	Active,

	Paused bool
	// Expiration is the expiration date of the cooldown.
	// If cooldown is inactive, it'll be zero time.Time,
	Expiration,

	PausedDate time.Time
}

BasicState represents the state of Basic cooldown.

type Context 

type Context = event.Context[*CoolDown]

type CoolDown 

type CoolDown struct {
	// contains filtered or unexported fields
}

CoolDown is the same Valued cooldown but without values. It uses underlying Valued with empty struct as value. The handler type is also different here, but its logic is the same, because it's just a wrapper for ValuedHandler.

func New 

func New(opts ...Option) *CoolDown

New creates new CoolDown instance.

func (*CoolDown) Active 

func (cooldown *CoolDown) Active() bool

Active ...

func (*CoolDown) ActiveUnsafe 

func (cooldown *CoolDown) ActiveUnsafe() bool

func (*CoolDown) Handle 

func (cooldown *CoolDown) Handle(handler Handler)

Handle ...

func (*CoolDown) Handler 

func (cooldown *CoolDown) Handler() Handler

Handler ...

func (*CoolDown) Pause 

func (cooldown *CoolDown) Pause() bool

Pause ...

func (*CoolDown) PauseUnsafe 

func (cooldown *CoolDown) PauseUnsafe() bool

func (*CoolDown) Remaining 

func (cooldown *CoolDown) Remaining() time.Duration

Remaining ...

func (*CoolDown) RemainingUnsafe 

func (cooldown *CoolDown) RemainingUnsafe() time.Duration

func (*CoolDown) Renew 

func (cooldown *CoolDown) Renew()

Renew ...

func (*CoolDown) RenewUnsafe 

func (cooldown *CoolDown) RenewUnsafe()

func (*CoolDown) Resume 

func (cooldown *CoolDown) Resume() bool

Resume ...

func (*CoolDown) ResumeUnsafe 

func (cooldown *CoolDown) ResumeUnsafe() bool

func (*CoolDown) Start 

func (cooldown *CoolDown) Start(dur time.Duration)

Start ...

func (*CoolDown) StartUnsafe 

func (cooldown *CoolDown) StartUnsafe(dur time.Duration)

func (*CoolDown) Stop 

func (cooldown *CoolDown) Stop()

Stop ...

func (*CoolDown) StopUnsafe 

func (cooldown *CoolDown) StopUnsafe()

func (*CoolDown) TogglePause 

func (cooldown *CoolDown) TogglePause() bool

TogglePause ...

func (*CoolDown) TogglePauseUnsafe 

func (cooldown *CoolDown) TogglePauseUnsafe() bool

func (*CoolDown) Valued 

func (cooldown *CoolDown) Valued() *Valued[struct{}]

Valued ...

type Handler 

type Handler interface {
	// HandleStart handles start of the cooldown allowing user to cancel it via
	// context.
	HandleStart(ctx *Context, dur time.Duration)
	// HandleRenew handles cooldown renew allowing user to cancel it via
	// context.
	HandleRenew(ctx *Context, dur time.Duration)
	// HandleStop handles stop of the cooldown. You can identify stop cause by
	// errors.Is method. Example:
	//
	// switch cause {
	// case cooldown.ErrStopCauseExpired:
	//    // ...
	// case cooldown.ErrStopCauseCancelled:
	//    // ...
	// }
	HandleStop(cooldown *CoolDown, cause StopCause)
	// HandlePause handles user pausing the cooldown allowing to cancel event
	// via context.
	HandlePause(ctx *Context)
	// HandleResume handles user resuming the cooldown allowing to cancel event
	// via context.
	HandleResume(ctx *Context)
}

Handler allows to handle actions with CoolDown, additionally providing a Context allowing to cancel the event.

Note: you're NOT allowed to call locking CoolDown methods on handler events, because it is already in lock. Otherwise, it'll cause deadlock. Note, that you're still able to use Unsafe methods.

type NopHandler 

type NopHandler struct{}

NopHandler is no-operation implementation of Handler.

func (NopHandler) HandlePause 

func (NopHandler) HandlePause(*Context)

func (NopHandler) HandleRenew 

func (NopHandler) HandleRenew(*Context, time.Duration)

func (NopHandler) HandleResume 

func (NopHandler) HandleResume(*Context)

func (NopHandler) HandleStart 

func (NopHandler) HandleStart(*Context, time.Duration)

func (NopHandler) HandleStop 

func (NopHandler) HandleStop(*CoolDown, StopCause)

type NopValuedHandler 

type NopValuedHandler[T any] struct{}

NopValuedHandler is no-operation implementation of ValuedHandler.

func (NopValuedHandler[T]) HandlePause 

func (NopValuedHandler[T]) HandlePause(*ValuedContext[T], T)

func (NopValuedHandler[T]) HandleRenew 

func (NopValuedHandler[T]) HandleRenew(*ValuedContext[T], time.Duration, T)

func (NopValuedHandler[T]) HandleResume 

func (NopValuedHandler[T]) HandleResume(*ValuedContext[T], T)

func (NopValuedHandler[T]) HandleStart 

func (NopValuedHandler[T]) HandleStart(*ValuedContext[T], time.Duration, T)

func (NopValuedHandler[T]) HandleStop 

func (NopValuedHandler[T]) HandleStop(*Valued[T], StopCause, T)

type Option 

type Option = func(cd *CoolDown)

Option is the option implementation for default CoolDown.

func OptionHandler 

func OptionHandler(h Handler) Option

type StopCause 

type StopCause error

StopCause is used to identify reason of cooldown stop.

type Valued 

type Valued[T any] struct {
	// contains filtered or unexported fields
}

Valued represents cooldown with renew ability and values. Point of values is to use them as transaction or context value.

func NewValued 

func NewValued[T any](opts ...ValuedOption[T]) *Valued[T]

NewValued creates new Valued cooldown.

func (*Valued[T]) Active 

func (cooldown *Valued[T]) Active() bool

Active ...

func (*Valued[T]) ActiveUnsafe 

func (cooldown *Valued[T]) ActiveUnsafe() bool

func (*Valued[T]) Duration 

func (cooldown *Valued[T]) Duration() time.Duration

Duration ...

func (*Valued[T]) DurationUnsafe 

func (cooldown *Valued[T]) DurationUnsafe() time.Duration

func (*Valued[T]) Handle 

func (cooldown *Valued[T]) Handle(handler ValuedHandler[T])

Handle ...

func (*Valued[T]) Handler 

func (cooldown *Valued[T]) Handler() ValuedHandler[T]

Handler ...

func (*Valued[T]) L 

func (cooldown *Valued[T]) L() *sync.RWMutex

func (*Valued[T]) Pause 

func (cooldown *Valued[T]) Pause(val T) bool

Pause ...

func (*Valued[T]) PauseUnsafe 

func (cooldown *Valued[T]) PauseUnsafe(val T) bool

func (*Valued[T]) Paused 

func (cooldown *Valued[T]) Paused() bool

Paused ...

func (*Valued[T]) PausedUnsafe 

func (cooldown *Valued[T]) PausedUnsafe() bool

func (*Valued[T]) Remaining 

func (cooldown *Valued[T]) Remaining() time.Duration

Remaining ...

func (*Valued[T]) RemainingUnsafe 

func (cooldown *Valued[T]) RemainingUnsafe() time.Duration

func (*Valued[T]) Renew 

func (cooldown *Valued[T]) Renew(val T)

Renew ...

func (*Valued[T]) RenewUnsafe 

func (cooldown *Valued[T]) RenewUnsafe(val T)

func (*Valued[T]) Resume 

func (cooldown *Valued[T]) Resume(val T) bool

Resume ...

func (*Valued[T]) ResumeUnsafe 

func (cooldown *Valued[T]) ResumeUnsafe(val T) bool

func (*Valued[T]) Start 

func (cooldown *Valued[T]) Start(dur time.Duration, val T) bool

Start ...

func (*Valued[T]) StartUnsafe 

func (cooldown *Valued[T]) StartUnsafe(dur time.Duration, val T) bool

func (*Valued[T]) Stop 

func (cooldown *Valued[T]) Stop(val T)

Stop ...

func (*Valued[T]) StopUnsafe 

func (cooldown *Valued[T]) StopUnsafe(val T)

func (*Valued[T]) TogglePause 

func (cooldown *Valued[T]) TogglePause(val T) bool

TogglePause ...

func (*Valued[T]) TogglePauseUnsafe 

func (cooldown *Valued[T]) TogglePauseUnsafe(val T) bool

type ValuedContext 

type ValuedContext[T any] = event.Context[*Valued[T]]

type ValuedHandler 

type ValuedHandler[T any] interface {
	// HandleStart handles start of the cooldown allowing user to cancel it via
	// context.
	HandleStart(ctx *ValuedContext[T], dur time.Duration, val T)
	// HandleRenew handles renew allowing user to cancel it via context.
	HandleRenew(ctx *ValuedContext[T], dur time.Duration, val T)
	// HandleStop handles stop of the cooldown. You can identify stop cause by
	// errors.Is method. Example:
	//
	// switch cause {
	// case cooldown.ErrStopCauseExpired:
	//    // ...
	// case cooldown.ErrStopCauseCancelled:
	//    // ...
	// }
	HandleStop(cooldown *Valued[T], cause StopCause, val T)
	// HandlePause handles user pausing the cooldown allowing to cancel event
	// via context.
	HandlePause(ctx *ValuedContext[T], val T)
	// HandleResume handles user resuming the cooldown allowing to cancel event
	// via context.
	HandleResume(ctx *ValuedContext[T], val T)
}

ValuedHandler allows to handle actions with Valued, additionally providing a ValuedContext allowing to cancel the event.

Note: you're NOT allowed to call locking Valued methods on handler events, because it is already in lock. Otherwise, it'll cause deadlock. Note, that you're still able to use Unsafe methods.

type ValuedOption 

type ValuedOption[T any] = func(cd *Valued[T])

ValuedOption is option implementation for the Valued cooldown.

func ValuedOptionHandler 

func ValuedOptionHandler[T any](h ValuedHandler[T]) ValuedOption[T]

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
handler command
value command
internal
event
Package event is copied from github.com/df-mc/dragonfly/server/event.
 Package event is copied from github.com/df-mc/dragonfly/server/event.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.