// taskswitch.h -- Cooperative task switching library for DJGPP
//
// Credit-based cooperative multitasking with task pausing.
// Each task receives (priority + 1) credits per scheduling round.
// Tasks run round-robin, consuming one credit per turn.  When all
// credits are spent, every ready task is refilled.  Higher-priority
// tasks run proportionally more often but never starve lower ones.

#ifndef TASKSWITCH_H
#define TASKSWITCH_H

#include <stdint.h>
#include <stdbool.h>

// Error codes
#define TS_OK        0
#define TS_ERR_INIT  (-1)
#define TS_ERR_PARAM (-2)
#define TS_ERR_FULL  (-3)
#define TS_ERR_NOMEM (-4)
#define TS_ERR_STATE (-5)

// Defaults
#define TS_DEFAULT_STACK_SIZE 8192
#define TS_NAME_MAX           32

// Priority levels
#define TS_PRIORITY_LOW    0
#define TS_PRIORITY_NORMAL 5
#define TS_PRIORITY_HIGH   10

// Task states
typedef enum {
    TaskStateReady      = 0,
    TaskStateRunning    = 1,
    TaskStatePaused     = 2,
    TaskStateTerminated = 3
} TaskStateE;

// Task entry function signature
typedef void (*TaskEntryT)(void *arg);

// Initialize the task system. The calling context becomes task 0 (main).
// maxTasks includes the main task slot.
int32_t tsInit(uint32_t maxTasks);

// Shut down the task system and free all resources.
void tsShutdown(void);

// Create a new task. Pass 0 for stackSize to use TS_DEFAULT_STACK_SIZE.
// Returns the task ID (>= 0) on success, or a negative error code.
int32_t tsCreate(const char *name, TaskEntryT entry, void *arg, uint32_t stackSize, int32_t priority);

// Yield CPU to the next eligible ready task (credit-based round-robin).
void tsYield(void);

// Pause a task. Cannot pause the main task (id 0).
// If a task pauses itself, an implicit yield occurs.
int32_t tsPause(uint32_t taskId);

// Resume a paused task.
int32_t tsResume(uint32_t taskId);

// Set a task's scheduling priority.
int32_t tsSetPriority(uint32_t taskId, int32_t priority);

// Get a task's priority, or TS_ERR_PARAM on invalid id.
int32_t tsGetPriority(uint32_t taskId);

// Get a task's current state.
TaskStateE tsGetState(uint32_t taskId);

// Get the currently running task's ID.
uint32_t tsCurrentId(void);

// Get a task's name, or NULL on invalid id.
const char *tsGetName(uint32_t taskId);

// Terminate the calling task. Must not be called from the main task.
void tsExit(void);

// Get the number of non-terminated tasks.
uint32_t tsActiveCount(void);

#endif // TASKSWITCH_H