<?php

declare(strict_types=1);

namespace App\Framework\Async\Contracts;

use App\Framework\Async\AsyncPromise;
use App\Framework\Core\ValueObjects\Duration;
use Fiber;

/**
 * Interface for async operations with timeout and cancellation support
 */
interface AsyncOperation
{
    /**
     * Execute the operation synchronously
     */
    public function execute(): mixed;

    /**
     * Execute the operation asynchronously
     */
    public function executeAsync(): Fiber;

    /**
     * Execute with timeout
     */
    public function executeWithTimeout(Duration $timeout): AsyncPromise;

    /**
     * Check if operation can be cancelled
     */
    public function isCancellable(): bool;

    /**
     * Cancel the operation if possible
     */
    public function cancel(): void;
}
