yieldpoint

README

yieldpoint

A Go package that enables cooperative goroutine yielding based on priority-aware scheduling.

Overview

yieldpoint provides a simple yet powerful mechanism for implementing cooperative multitasking in Go applications. It allows goroutines to voluntarily yield execution when high-priority tasks are active.

Features

• Priority-based Yielding: Goroutines can yield execution when high-priority tasks are active
• Efficient Blocking: Uses sync.Cond for efficient blocking without busy waiting
• Context Support: Context-aware variants of all operations
• High Priority Support: Simple boolean flag for high-priority tasks
• Thread Safety: All operations are thread-safe
• Nesting Support: High-priority sections can be nested

Installation

go get github.com/AlexsanderHamir/yieldpoint

Usage

Basic Usage

package main

import "github.com/AlexsanderHamir/yieldpoint"

func main() {
    // Start a high-priority section
    yieldpoint.EnterHighPriority()
    defer yieldpoint.ExitHighPriority()

    // In another goroutine
    go func() {
        // This will yield if high-priority is active
        yieldpoint.MaybeYield()

        // Or block until high-priority ends
        yieldpoint.WaitIfActive()

        // higher performance
        yieldpoint.MaybeYieldFast()

        // higher performance
        yieldpoint.WaitIfActiveFast()
    }()
}

Context Support

ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()

// Yield with context
err := yieldpoint.MaybeYieldWithContext(ctx)
if err != nil {
    // Handle context cancellation
}

// Wait with context
err = yieldpoint.WaitIfActiveWithContext(ctx)
if err != nil {
    // Handle context cancellation
}

API Reference

Core Functions

• MaybeYield(): Voluntarily yields if high-priority is active
• EnterHighPriority(): Begins a high-priority section
• ExitHighPriority(): Ends a high-priority section
• WaitIfActive(): Blocks until high-priority section ends
• IsHighPriorityActive(): Checks if any high-priority sections are active

Configuration Functions

• SetSpinWaitIterations(iterations int): Sets the number of spin iterations before falling back to blocking wait. This setting applies to the fast variant WaitIfActiveFast.
• SetDefaultYieldDuration(duration time.Duration): Sets the default duration for yielding operations. This setting applies to the standard MaybeYield to ensure it yields.

High Performance Functions

• MaybeYieldFast(): High performance version
• WaitIfActiveFast(): High performance version

Context-aware Functions

• MaybeYieldWithContext(ctx context.Context) error
• WaitIfActiveWithContext(ctx context.Context) error

Contributions

Share your talents and ideas !!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package yieldpoint provides cooperative goroutine yielding based on priority-aware scheduling.

Index

• Variables
• func EnterHighPriority()
• func ExitHighPriority()
• func IsHighPriorityActive() bool
• func MaybeYield()
• func MaybeYieldFast()
• func MaybeYieldWithContext(ctx context.Context) error
• func SetDefaultYieldDuration(d time.Duration)
• func SetSpinWaitIterations(n int)
• func WaitIfActive()
• func WaitIfActiveFast()
• func WaitIfActiveWithContext(ctx context.Context) error

Variables

var Cond = sync.NewCond(&Mu)

Cond is the condition variable used for efficient blocking

var DefaultYieldDuration = 1 * time.Millisecond

DefaultYieldDuration is the default duration to sleep when yielding

var HighPriorityCount atomic.Int32

HighPriorityCount tracks the number of active high-priority sections

var Mu sync.Mutex

Mu is the mutex used for efficient blocking in WaitIfActive

var SpinWaitIterations = 1000

SpinWaitIterations is the number of iterations to spin-wait before falling back to mutex-based waiting

Functions

func EnterHighPriority

func EnterHighPriority()

EnterHighPriority begins a high-priority section. Multiple calls are supported through reference counting.

func ExitHighPriority

func ExitHighPriority()

ExitHighPriority ends a high-priority section. If this is the last high-priority section, it will signal any waiting goroutines.

func IsHighPriorityActive

func IsHighPriorityActive() bool

IsHighPriorityActive returns true if any high-priority sections are currently active.

func MaybeYield

func MaybeYield()

MaybeYield voluntarily yields the current goroutine if any high-priority sections are active. This is a non-blocking operation that uses runtime.Gosched() combined with a small sleep to ensure effective processor yielding.

func MaybeYieldFast

func MaybeYieldFast()

MaybeYieldFast is a high-performance version of MaybeYield that avoids time.Sleep and uses only runtime.Gosched() for minimal overhead. This is suitable for performance-critical code paths where the exact timing of yields is less important.

func MaybeYieldWithContext

func MaybeYieldWithContext(ctx context.Context) error

MaybeYieldWithContext is a context-aware version of MaybeYield

func SetDefaultYieldDuration

func SetDefaultYieldDuration(d time.Duration)

SetDefaultYieldDuration sets the default duration to sleep when yielding

func SetSpinWaitIterations

func SetSpinWaitIterations(n int)

SetSpinWaitIterations sets the number of iterations to spin-wait before falling back to mutex-based waiting

func WaitIfActive

func WaitIfActive()

WaitIfActive blocks the current goroutine until no high-priority sections are active. This is an efficient blocking operation that uses sync.Cond to avoid busy waiting.

func WaitIfActiveFast

func WaitIfActiveFast()

WaitIfActiveFast is a high-performance version of WaitIfActive that uses a spin-wait strategy before falling back to mutex-based waiting. This is suitable for performance-critical code paths where the wait time is expected to be very short.

func WaitIfActiveWithContext

func WaitIfActiveWithContext(ctx context.Context) error

WaitIfActiveWithContext is a context-aware version of WaitIfActive