Skip to main content

Task Queue

Queue is the central component of Ziva that manages sequential task execution and provides a unified interface for user interaction.

Creating a Queue

queue := ziva.NewQueue("Queue title")
Screenshot: queue summary view

Main Methods

Adding Tasks

// Add single task
queue.AddTasks(task1)

// Add multiple tasks
queue.AddTasks(task1, task2, task3)

// Chained addition
queue.AddTasks(task1).AddTasks(task2)

Running the Queue

if err := queue.Run(); err != nil {
    log.Fatal(err)
}

Display Configuration

Application Name

queue.WithAppName("MyApplication")

Name and Title Colors

// Application name color
queue.WithAppNameColor(ziva.BlueBright, true) // color, bold

// Queue title color
queue.WithTitleColor(ziva.GreenBright, false) // color, normal

Task Numbering

// Enable numbering with format
queue.WithTasksNumbered(true, "[%02d]") // [01], [02], [03]...

// Alternative formats
queue.WithTasksNumbered(true, "(%d)")   // (1), (2), (3)...
queue.WithTasksNumbered(true, "%d.")    // 1., 2., 3....

// Keep first character of format
queue.WithTasksNumbered(true, "[%02d]") // preserve '['

Summary Management

// Disable completion summary
queue.WithOutSummary()

// Disable result separator lines
queue.WithOutResultLine()

Screen Clearing

// Clear screen before running
queue.WithClearScreen(true)

Error Management

Error Color Configuration

// Import error types
import "github.com/qzeleza/ziva/internal/query"

// Set error color
queue.SetErrorColor(query.ErrorColorRed)    // Red
queue.SetErrorColor(query.ErrorColorYellow) // Yellow
queue.SetErrorColor(query.ErrorColorNone)   // No color

Configuration Examples

Minimal Configuration

queue := ziva.NewQueue("Simple application")
queue.AddTasks(task1, task2)
queue.Run()

Full Configuration

queue := ziva.NewQueue("Advanced TUI Application")
queue.WithAppName("AdvancedApp").
      WithAppNameColor(ziva.BlueBright, true).
      WithTitleColor(ziva.GreenBright, false).
      WithTasksNumbered(true, "[%02d]").
      WithClearScreen(true).
      WithOutResultLine().
      SetErrorColor(query.ErrorColorRed)

queue.AddTasks(
    confirmTask,
    selectTask,
    inputTask,
    functionTask,
)

if err := queue.Run(); err != nil {
    log.Fatalf("Execution error: %v", err)
}

Embedded Systems Configuration

queue := ziva.NewQueue("IoT Configuration")
queue.WithAppName("RouterSetup").
      WithOutSummary().        // Space saving
      WithOutResultLine().         // Simplified output
      WithTasksNumbered(false, ""). // No numbering
      WithClearScreen(false)       // Preserve context

// Use simplified colors
queue.WithAppNameColor(ziva.WhiteBright, false).
      WithTitleColor(ziva.GrayBright, false)

Queue Lifecycle

  1. Creation - NewQueue(title)
  2. Configuration - With* method calls
  3. Task Addition - AddTasks(...)
  4. Execution - Run()

State Handling

Successful Execution

When all tasks complete successfully, Run() returns nil.

User Cancellation

If the user cancels execution (Ctrl+C), the queue terminates gracefully.

Execution Errors

if err := queue.Run(); err != nil {
    switch err {
    case context.Canceled:
        fmt.Println("Execution canceled by user")
    default:
        fmt.Printf("Error: %v\n", err)
    }
}

Performance Optimization

For Large Queues

// Limit completed task history
os.Setenv("ZIVA_MAX_COMPLETED_TASKS", "5")

// Memory monitoring
os.Setenv("ZIVA_MEMORY_PRESSURE_THRESHOLD", "100M")

For Slow Terminals

// Simplified display mode
queue.WithOutResultLine().
      WithOutSummary().
      WithTasksNumbered(false, "")
Tip: Experiment with different settings to achieve optimal user experience in your specific environment.

See Also

I