module async

import context
import sync

struct TaskResult[T] {
	value T
	err   IError = none
}

// Task represents one concurrent computation that produces either a value or an error.
//
// A Task is intentionally small: it starts one `spawn`, stores one result in a
// bounded channel, and lets the owner consume that result with wait(). It does
// not recover panics and it does not kill work that ignores cancellation.
@[heap]
pub struct Task[T] {
mut:
	ctx       context.Context
	cancel    context.CancelFn = unsafe { nil }
	result_ch chan TaskResult[T]
	// Guards the one-shot wait contract. The result channel carries the actual
	// value/error, so no additional shared result state is needed.
	mutex  &sync.Mutex = sync.new_mutex()
	waited bool
}

// run starts f with a background context and returns a Task for its result.
//
// The returned Task owns a derived context that is canceled when f finishes.
pub fn run[T](f TaskFn[T]) !&Task[T] {
	return run_with_context[T](context.background(), f)
}

// run_with_context starts f with a context derived from parent.
//
// Cancellation is cooperative. If parent is canceled, f must observe ctx.done()
// and return. The result channel is buffered so f can publish its single result
// even if the owner has not called wait() yet.
pub fn run_with_context[T](parent context.Context, f TaskFn[T]) !&Task[T] {
	if f == unsafe { nil } {
		return error(err_nil_job)
	}
	ctx, cancel := new_cancel_context(parent)
	mut task := &Task[T]{
		ctx:       context.Context(ctx)
		cancel:    cancel
		result_ch: chan TaskResult[T]{cap: 1}
		mutex:     sync.new_mutex()
	}
	spawn fn [T](task &Task[T], f TaskFn[T]) {
		mut job_ctx := task.ctx
		value := f(mut job_ctx) or {
			task.result_ch <- TaskResult[T]{
				err: err
			}
			task.cancel()
			return
		}
		task.result_ch <- TaskResult[T]{
			value: value
		}
		task.cancel()
	}(task, f)
	return task
}

// wait blocks until the task publishes its result, then returns the value or error.
//
// wait is one-shot. A second call returns a stable error instead of blocking on
// an already-consumed result channel.
pub fn (mut task Task[T]) wait() !T {
	task.mutex.lock()
	if task.waited {
		task.mutex.unlock()
		return error(err_task_wait_called)
	}
	task.waited = true
	task.mutex.unlock()

	result := <-task.result_ch
	if result.err !is none {
		return result.err
	}
	return result.value
}