proposal: time: new Init() and Start() methods for Timer

[OmidHekayati]

As suggested here #54861 by add these two new methods to time package, we achieve this goals:

• Changes don't break any existing code and respect backward compatibility.
• prevent two heap allocation (unnecessary) request, when a Timer can be part of other structs (embed or as a field).
• Due to NewTimer can't inline and return the pointer of a Timer struct,
  If devs want to add a Timer to other structs (embed or as a field) to allocate both structs in one request,
  existing NewTimer() don't let us do this.
• Init method can inline now and the Start() method sets the when field. In this way, functions respect the single responsibility principle.

/time> go build -gcflags="-m"
./sleep.go:64:6: can inline (*Timer).Init
./sleep.go:50:8: inlining call to (*Timer).Init

• Improve code readability of NewTimer() function.

[seankhliao]

please include the proposed function signatures and a description of what they do here.

[OmidHekayati]

Proposed function signatures:

func (t *Timer) Init()
func (t *Timer) Start(d Duration)

func (t *Ticker) Init()
func (t *Ticker) Tick(d Duration)

Keep in mind that these new methods is not introduce new functionality, They just get some functionalities from NewTimer & NewTicker and made them be simple. Init() method as usuall initialize the new allocated object. Start() or Tick() method will start timer(runtime package) that will send signal (on the channel) once or on periods base on its type.

[ianlancetaylor]

Please write doc comments for these new methods. Thanks. In particular, what does the Init method do? Why do we need it?

[OmidHekayati]

Although I wrote comments in #54861, you are right I must copy them here for better referencing.

// Init initialize the Timer.
// It must call before call Start() or Reset() methods
func (t *Timer) Init()
// Start start the timer that will send
// the current time on its channel after at least duration d.
func (t *Timer) Start(d Duration)

// Init initialize the Ticker.
// It must call before call Tick() or Reset() methods
func (t *Ticker) Init()
// Tick start the timer that will send
// the current time on its channel after each tick.
func (t *Ticker) Tick(d Duration)

As said in the first comment, Due to NewTimer or NewTicker returning a pointer of Timer or Ticker and they can't be inlined, So when we can embed Timer or Ticker we don't have a way to Init them without unnecessary heap allocation. When Init exist we can easily add Timer or Ticker to other structs with one heap allocation request.

type HeartBeatService struct {
	// other fields
	interval time.Duration
	ticker   time.Ticker
}

func (h *HeartBeatService) Init(interval time.Duration) {
	h.interval = interval
	h.ticker.Init()
}
func (h *HeartBeatService) Reinit() {
	h.ticker.Stop()
	// can flush h.ticker.C here too.
}
func (h *HeartBeatService) Deinit() {
	h.ticker.Stop()
}

func (h *HeartBeatService) Process() {
	h.ticker.Start(h.interval)

	for now := range h.ticker.C {
		// send signal
	}
}

In this way, each new methods have a single responsibility and complete the life cycle of Timer or Ticker, And prevents congested logic in NewTimer or NewTicker.

[rsc]

What does Init do that Start cannot do instead?

[OmidHekayati]

@rsc Init exist to show object(Timer) life cycle and respect functions single responsibility. (Personally I like a code that respect these principles).

But anyway you are the ruler, if you don't like Init exported method, just accept the Start exported method. But take in mind that we need init local method any way, because Timer let us call its Reset method in not started timer. So We need to check for not initialized timer in both Start and Reset or change the Reset documents.

[rsc]

It sounds like the goal is purely to avoid allocations. But each Timer is kept in a heap stored in the runtime, and we don't want the runtime's copy to be writable by user code, or else the heap invariants can be violated. So I don't think we want the runtime to allow the user to provide the memory for a Timer.

Is there a program or real-world benchmark you can point to that is suffering from these allocations?

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[OmidHekayati]

It sounds like the goal is purely to avoid allocations. But each Timer is kept in a heap stored in the runtime, and we don't want the runtime's copy to be writable by user code, or else the heap invariants can be violated.

@rsc How runtime's copy can be writable by user code?
Can you explain when all fields of runtimeTimer are privates user can change them directly without any exported methods?

So I don't think we want the runtime to allow the user to provide the memory for a Timer.

When any developer decides to embed a structure into another one, It means that have enough knowledge about bad things that may happen like memory leaks and it is like many other features in Go such as string that can be a huge problem if we don't be careful.

Is there a program or real-world benchmark you can point to that is suffering from these allocations?

I know the usage of proposed APIs is rare (in comparison to other features) and usually used in low-level libraries such as /runtime/netpoll.go/pollDesc but it can be a helpful feature in some use-cases like implementing network protocols in user space (instead of kernel space) as QUIC.
I think writing many things in user space (as OS-library) is the future way to develop computer software.

P.S.: I try to rewrite the timer package and get all functionality away from the Go runtime and time packages, It is not ready to use yet but it is a possible way.
I think the Go runtime package needs many rewrite to be small and just a wrapper of functionalities not an implementor of them.
https://github.com/GeniusesGroup/libgo/tree/dev/timer

[ianlancetaylor]

The fact that the fields are private doesn't prevent someone from writing

    var v HeartBeatService
    v.Init()
    v  = HeartBeatService{}

I try to rewrite the timer package and get all functionality away from the Go runtime and time packages, It is not ready to use yet but it is a possible way.
I think the Go runtime package needs many rewrite to be small and just a wrapper of functionalities not an implementor of them.

That is interesting. The current timer implementation is closely tied to the scheduler, as I expect you know. This has been guided by a desire for efficiency and timer accuracy, especially for programs with millions of timers. That is, performance and accuracy are extremely important here. If we can get comparable results by moving this out of the runtime, that would be great. But it sounds hard.