// Package backgroundtask provides a robust background task runner that executes
// work functions on a periodic schedule or when signaled. The runner supports:
//
//   - Periodic execution based on a configurable interval
//   - On-demand execution via signal
//   - Graceful shutdown with timeout
//   - Work coalescing to prevent concurrent executions
//   - Statistics tracking for observability
//   - Thread-safe operation
//
// Basic usage:
//
//	config := map[string]any{
//	    "myData": getYourData(),
//	    "settings": getYourSettings(),
//	}
//	logger := slog.Default()
//	workFunc := func(ctx context.Context, logger *slog.Logger, config map[string]any) error {
//	    // Your work logic here
//	    return nil
//	}
//
//	runner, err := backgroundtask.Initialize(config, logger, workFunc,
//	    backgroundtask.WithInterval(30 * time.Second))
//	if err != nil {
//	    // Handle error
//	}
//
//	runner.Run()
//	// ... do other work ...
//	runner.Signal() // Trigger immediate execution
//	// ... when shutting down ...
//	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
//	defer cancel()
//	if err := runner.Shutdown(ctx); err != nil {
//	    // Handle timeout
//	}
//
// Note: This package is currently under development. Some fields and methods
// are defined but not yet implemented, which will cause unused warnings during
// the build process. These will be resolved as implementation progresses.
package backgroundtask