ltask-go

A Go implementation of cloudwu/ltask - a Lua task library with n:m scheduler that enables running M Lua VMs on N OS threads.

⚠️ Caution

This library is currently working in progress 🚧. APIs are not stable and may undergo breaking changes. It is not recommended for production use at this time.

Features

• N:M Scheduler: Run multiple Lua VMs efficiently across OS threads
• Bootstrap Architecture: Proper service initialization through bootstrap process
• Embedded Lua Runtime: Built-in Lua support with embedded glue code
• Service Management: Lightweight service model for concurrent tasks
• Cross-Platform: Works on Windows, Linux, and macOS

Quick Start

Installation

go get go.yuchanns.xyz/ltask

Basic Usage Pattern

ltask-go follows the bootstrap pattern used in the test files. Create a main Lua file that requires the bootstrap module and starts the system:

-- main.lua
local start = require("test.start")

start({
    core = {
        worker = 3,  -- Number of worker threads
        -- debuglog = "=",  -- Uncomment for debug output
    },
    service_path = "service/?.lua",  -- Service search path
    bootstrap = {
        {
            name = "timer",
            unique = true,
            builtin = true,
        },
        {
            name = "logger", 
            unique = true,
            builtin = true,
        },
        {
            name = "my_service",  -- Your custom service
            unique = false,
        }
    }
})

Creating a Service

Create a service file. The service path is configurable in the bootstrap setup:

-- service/my_service.lua
local ltask = require "ltask"

local my_service = {}

function my_service.echo(message)
    print("Service received:", message)
    return "Echo: " .. message
end

function my_service.ping()
    return "pong"
end

return my_service

The service will be automatically loaded when referenced in the bootstrap configuration.

Core Concepts

Bootstrap Process

ltask-go requires a proper bootstrap sequence:

1. Require bootstrap: local boot = require("ltask.bootstrap")
2. Search embedded files: Use boot.searchpath() to find embedded Lua modules
3. Load bootstrap: boot.dofile() to load the main bootstrap module
4. Start system: bootstrap.start() with configuration
5. Wait for completion: bootstrap.wait() to keep the system running

Service Configuration

Services are configured through the bootstrap process. The loading behavior is completely customizable via initfunc:

• unique: Whether only one instance is allowed
• service_path: Where to search for service files
• initfunc: Custom function to control how services are loaded (completely flexible)

Different examples show different initfunc implementations:

• Root test: Uses ltask.searchpath and ltask.loadfile for embedded services
• Sokol example: Uses standard package.searchpath and loadfile for external services

Examples

Explore the provided examples for proper usage patterns:

• test.lua - Main test entry point
• test/start.lua - Bootstrap implementation
• test/user.lua - Example service implementation
• examples/ - Application examples, such as sokol-integration

Running the Tests

# Clone the repository and submodules
git clone --recurse-submodules https://github.com/yuchanns/ltask-go
git clone --recurse-submodules https://github.com/yuchanns/lua

go work init
go work use ./ltask-go
go work use ./lua

# Build Lua library
cd lua && luamake && cd -

# Run tests
cd ltask-go && go test -v ./...

Credits

This project is a Go rewrite of cloudwu/ltask, originally created by 云风.

License

Apache License 2.0 - see LICENSE for details.