Libmedia Cheap

https://github.com/zhaohappy/cheap
Admin
A TypeScript development library for multi-threaded JavaScript and high-performance WebAssembly...
Tokens:22,191
Snippets:161
Trust Score:6.4
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install @libmedia/cheap Package

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Use npm to install the cheap package. This is the first step to integrating cheap into your project.

```bash
npm install @libmedia/cheap
```

--------------------------------

### Configure tsconfig.json for Cheap

Source: https://context7.com/zhaohappy/cheap/llms.txt

Configure tsconfig.json to include Cheap's definition file and enable multi-threading with defined macros. This setup specifies module resolution and path mappings for Cheap modules.

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "baseUrl": "./",
    "paths": {
      "@libmedia/cheap/*": ["node_modules/@libmedia/cheap/dist/esm/*"]
    }
  },
  "files": [
    "node_modules/@libmedia/cheap/dist/esm/cheapdef.d.ts"
  ],
  "cheap": {
    "defined": {
      "ENABLE_THREADS": true
    }
  },
  "include": ["src/**/*"]
}

```

--------------------------------

### Vite Worker Configuration

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Example Vite configuration for setting up TypeScript compilation with transformers for worker threads.

```javascript
import { defineConfig } from 'vite';
import typescript from '@rollup/plugin-typescript';
import * as transformer from '@libmedia/cheap/build/transformer';

export default defineConfig({
  ...
  worker: {
    plugins: () => {
      return [
        typescript({
          ...
          transformers: {
            before: [
              {
                type: 'program',
                factory: (program) => {
                  return transformer.before(program);
                }
              }
            ]
          }
          ...
        }),
      ]
    }
  }
  ...
```

--------------------------------

### Vite Multi-Thread Usage

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Example of creating a thread from a function using Vite's worker import syntax.

```javascript
import task from './task'
import worker from './worker?worker'

const pipeline = await createThreadFromFunction(
  task,
  worker
).run()
```

--------------------------------

### Webpack Multi-Thread Usage

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Example of creating a thread from a function using Webpack's worker-loader.

```javascript
import task from './task'
import worker from 'worker-loader!./worker'

const pipeline = await createThreadFromFunction(
  task,
  worker
).run()
```

--------------------------------

### Configure Webpack with CheapPlugin

Source: https://context7.com/zhaohappy/cheap/llms.txt

Configure webpack to use the CheapPlugin for simplified multi-threading support. This setup includes ts-loader for TypeScript files and defines macros for conditional compilation.

```javascript
// webpack.config.js
const path = require('path');
const CheapPlugin = require('@libmedia/cheap/build/webpack/CheapPlugin');

module.exports = (env) => {
  return {
    entry: './src/index.ts',
    output: {
      path: path.resolve(__dirname, 'dist'),
      filename: 'bundle.js'
    },
    resolve: {
      extensions: ['.ts', '.js']
    },
    module: {
      rules: [
        {
          test: /\.ts$/,
          use: [
            {
              loader: 'ts-loader'
            }
          ],
          exclude: /node_modules/
        }
      ]
    },
    plugins: [
      new CheapPlugin({
        // Environment: 'browser' or 'node'
        env: 'browser',
        // Project root directory
        projectPath: __dirname,
        // Files to exclude from transformation
        exclude: /__test__|\.spec\.ts$/,
        // Macro definitions for conditional compilation
        defined: {
          DEBUG: process.env.NODE_ENV !== 'production',
          ENABLE_LOGGING: true
        }
      })
    ]
  };
};

```

--------------------------------

### Node.js Multi-Thread Usage

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Example of creating a thread from a function using Node.js's worker_threads module.

```javascript
import task from './task'
import { Worker } from 'worker_threads'

const pipeline = await createThreadFromFunction(
  task,
  () => new Worker(require.resolve('./worker'))
).run()
```

--------------------------------

### Webpack Multi-Threads without Separate Entry

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Example of using createThreadFromFunction with Webpack without a separate worker entry file, enabling runtime code generation for workers.

```javascript
import task from './task'

const pipeline = await createThreadFromFunction(
  task
).run()
```

--------------------------------

### SharedPtr Interface Methods

Source: https://github.com/zhaohappy/cheap/blob/master/README.md

Defines the interface for SharedPtr, including methods to get the raw pointer, reset, check for uniqueness, get the use count, check for existence, convert to a transferable object, and clone.

```typescript
interface SharedPtr<T> {
  /**
   * 获取原始指针
   */
  get(): pointer<T>
  /**
   * 重置原始指针
   */
  reset(value?: pointer<T>): void
  /**
   * 返回当前的原始指针是否只有一个引用
   */
  unique(): boolean
  /**
   * 返回当前的原始指针引用计数
   */
  useCount(): int32
  /**
   * 是否有原始指针
   */
  has(): boolean
  /**
   * 将智能指针转为可转移对象
   */
  transferable(): SharedPtrTransferable<T>
  /**
   * 克隆智能指针（增加引用计数）
   */
  clone(): SharedPtr<T>
}
```

--------------------------------

### SharedPtr Interface Methods

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Defines the interface for SharedPtr, including methods to get the raw pointer, reset it, check for unique references, get the reference count, check for existence, convert to a transferable object, and clone the pointer.

```typescript
interface SharedPtr<T> {
  /**
   * Get the raw pointer
   */
  get(): pointer<T>
  /**
   * Reset the raw pointer
   */
  reset(value?: pointer<T>): void
  /**
   * Returns whether the current raw pointer has only one reference
   */
  unique(): boolean
  /**
   * Returns the reference count of the raw pointer
   */
  useCount(): int32
  /**
   * Returns whether has raw pointer
   */
  has(): boolean
  /**
   * Convert smart pointer to transferable object
   */
  transferable(): SharedPtrTransferable<T>
  /**
   * Clone a smart pointer (increase reference count)
   */
  clone(): SharedPtr<T>
}
```

--------------------------------

### Inter-thread SharedPtr Transfer

Source: https://github.com/zhaohappy/cheap/blob/master/README.md

Example of transferring a SharedPtr between threads using transferable objects and de-transferring it in the worker. Note the recommendation to use raw pointers for frequent inter-thread data transfer.

```typescript
import { createThreadFromFunction, deTransferableSharedPtr } from '@libmedia/cheap'

@struct
class MyStruct {
  a: int8
}

function worker(t: SharedPtrTransferable<MyStruct>) {
  const p = deTransferableSharedPtr(t)
  console.log(p.a)
}

const p = make_shared_ptr<MyStruct>()
const transfer = p.transferable()
const thread = await createThreadFromFunction(worker).transfer(transfer.buffer).run(transfer)
```

--------------------------------

### Compile Node.js with TypeScript Transformer

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Use this script to compile TypeScript code in a Node.js project using the TypeScript compiler API and a custom transformer. Ensure you have 'typescript' and '@libmedia/cheap' installed. Configure your 'tsconfig.json' path correctly.

```javascript
const fs = require('fs')
const path = require('path')
const ts = require('typescript')
const transformer = require('@libmedia/cheap/build/transformer')

// Read tsconfig.json configuration and change the path to your own tsconfig.json
const configPath = path.resolve(__dirname, './tsconfig.json')
const configText = fs.readFileSync(configPath, 'utf8')
const { config } = ts.parseConfigFileTextToJson(configPath, configText)
const parsedCommandLine = ts.parseJsonConfigFileContent(
  config,
  ts.sys,
  path.dirname(configPath)
)
const program = ts.createProgram(parsedCommandLine.fileNames, parsedCommandLine.options)
const emitResult = program.emit(undefined, undefined, undefined, undefined, {
  before: [
    transformer.before(program)
  ]
})
const allDiagnostics = ts
  .getPreEmitDiagnostics(program)
  .concat(emitResult.diagnostics)

allDiagnostics.forEach((diagnostic) => {
  if (diagnostic.file) {
    const { line, character } = 
      diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
    const message = ts.flattenDiagnosticMessageText(
      diagnostic.messageText,
      '\n'
    );
    console.log(
      `${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`
    );
  } else {
    console.log(
      ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')
    );
  }
})
```

--------------------------------

### Instantiate and Manage Structs in Cheap

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Structs can be instantiated using 'make' with initial data, returning a Proxy object. Memory must be explicitly managed using 'unmake' and 'malloc'/'free' for pointer-based instances. Pointer arithmetic and access follow C-like rules.

```typescript
@struct
class MyStruct {
  a: int8
  b: uint32
}

// Create a struct instance, can pass initialization data
// The return of make is a js object use Proxy
// The getter and setter logic used every time when reading and writing properties
const myStruct = make<MyStruct>({ a: 0, b: 0 })
myStruct.a = 3
myStruct.b = 4
console.log(myStruct.b)

// destroy struct instance
unmake(myStruct)

// Create a struct pointer (recommended, most efficient)
let myStructPointer = reinterpret_cast<pointer<MyStruct>>(malloc(sizeof(MyStruct)))
// pointer can be assigned values through properties
myStructPointer.a = 0
myStructPointer.b = 1
// pointer can got value of properties
console.log(myStructPointer.b)

// the type of pa pointer<int8>
// equal to 'int8* pa = &myStructPointer->a' in C
const pa = addressof(myStructPointer.a)
// equal to 'int8 va = *pa' in C
const va = accessof(pa)

// pointer can be used as array
// equal to 'accessof(pa + 3)'
const aa = pa[3]

// equal to '*va = (int8)34' in C
// since function calls in js cannot be Lvalue, a '<-' syntax is added
// But there is a small flaw. If the types on both sides are structures, an error will be reported. You need to use @ts-ignore to ignore it.
// or use 'pa[0] = static_cast<int8>(34)' it will not report an error
accessof(pa) <- static_cast<int8>(34)

// pointer can be incremented and decremented, and can be added to numbers. Two pointers of the same type can be subtracted. The rules are the same as C.
// + 1 means that the pointer is offset by the size of the pointer type bytes, not 1 byte
// pointer<uint8>++ offset 1 byte
// pointer<uint64>++ offset 8 bytes
pa++
pa--
pa += 8

// delete struct memory
free(myStructPointer)
// 'nullptr' is null pointer definition
myStructPointer = nullptr

```

--------------------------------

### SharedPtr Constructors and Usage

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Demonstrates how to create SharedPtr instances with and without initial values, and with custom destructors. Accessing raw pointer properties and their addresses is also shown.

```typescript
@struct
class MyStruct {
  a: int8
}

// Constructor with no parameter 
const p0 = make_shared_ptr<MyStruct>()
const p1 = make_shared_ptr<int32>()
// Constructor with initialized data
const p2 = make_shared_ptr<MyStruct>({a: 0})
const p3 = make_shared_ptr<int32>(43)

function freeMyStruct(p: pointer<MyStruct>) {
  free(p)
}
// Constructor with a custom destructor
// If the destructor is not pass, the default destructor will only free the structure's own memory
const p4 = make_shared_ptr<MyStruct>(freeMyStruct)

// Constructor with initialized data and custom destructor
const p5 = make_shared_ptr<MyStruct>({a: 0}, freeMyStruct)

// Access the properties's value of the raw pointer
console.log(p5.a)
// Get the properties's address of the raw pointer
console.log(addressof(p5.a))
```

--------------------------------

### Configure tsconfig.json for Cheap

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Set up your tsconfig.json to correctly resolve paths and include necessary type definitions for @libmedia/cheap. This configuration is essential for TypeScript projects using cheap.

```json
{
  "baseUrl": "./",
  "paths": {
    ...
    "@libmedia/cheap/*": ["node_modules/@libmedia/cheap/dist/esm/*"]
  },
  "files": [
    "node_modules/@libmedia/cheap/dist/esm/cheapdef.d.ts"
  ],
  "cheap": {
    //  can add macro definition here
    "defined": {

    }
  }
}
```

--------------------------------

### Perform Pointer Operations with Cheap

Source: https://context7.com/zhaohappy/cheap/llms.txt

Illustrates C-style pointer operations including memory allocation, dereferencing, address-of, and arithmetic. Essential for WebAssembly interoperability and efficient memory management. Remember to free allocated memory.

```typescript
import { addressof, sizeof, memset, memcpy } from '@libmedia/cheap'

@struct
class DataBuffer {
  size: uint32
  data: pointer<uint8>
}

// Allocate memory and create a pointer to struct
let bufferPtr = reinterpret_cast<pointer<DataBuffer>>(malloc(sizeof(DataBuffer)))

// Initialize the struct through pointer
bufferPtr.size = 1024
bufferPtr.data = reinterpret_cast<pointer<uint8>>(malloc(1024))

// Initialize buffer with zeros
memset(bufferPtr.data, 0, 1024)

// Get address of a struct member
const sizeAddress = addressof(bufferPtr.size)
console.log(`Size field address: ${sizeAddress}`)

// Access pointer value using accessof
const dataPtr = bufferPtr.data
const firstByte = accessof(dataPtr)  // Read first byte

// Pointer arithmetic (moves by sizeof(type) bytes)
const thirdByte = dataPtr[2]  // Access third element
dataPtr[0] = static_cast<uint8>(255)  // Write to first element

// Pointer increment/decrement
let ptr = bufferPtr.data
ptr++  // Advance by 1 byte (uint8)
ptr += 10  // Advance by 10 bytes

// Copy memory between regions
const destPtr = reinterpret_cast<pointer<uint8>>(malloc(512))
memcpy(destPtr, bufferPtr.data, 512)

// Clean up
free(bufferPtr.data)
free(bufferPtr)
free(destPtr)
```

--------------------------------

### Load and Run WebAssembly Module in Cheap

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Load a compiled WebAssembly resource using compileResource and execute it with WebAssemblyRunner. Functions exported by the wasm module can then be invoked.

```javascript
import { WebAssemblyRunner, compileResource } from '@libmedia/cheap'

// The resource can be stored in indexDB and taken out directly for use next time without having to perform network requests and compilation.
const resource = await compileResource(
  {
    source: 'https://xxxx.wasm'
  }
)

const runner = new WebAssemblyRunner(resource)
await runner.run()

// Then you can call the function exported by wasm
runner.invoke('func_a', 0)
```

--------------------------------

### Compile C/C++ to WebAssembly Module

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Use emcc to compile C/C++ code into a WebAssembly module in dynamic linking mode. Ensure specific flags are set for optimal integration with Cheap's runtime.

```shell
emcc -O3 xx.c 
  -s WASM=1 \
  -s FILESYSTEM=0 \
  -s FETCH=0 \
  -s ASSERTIONS=0 \
  -s ALLOW_MEMORY_GROWTH=1 \
  -s IMPORTED_MEMORY=1 \
  -s INITIAL_MEMORY=17367040 \
  -s USE_PTHREADS=0 \
  -s MAIN_MODULE=2 \
  -s SIDE_MODULE=0 \
  -s MALLOC="none" \
  -s ERROR_ON_UNDEFINED_SYMBOLS=0 \
  -o xx.wasm
```

--------------------------------

### Configure Vite for Cheap Transformer

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Set up the typescript plugin in your Vite configuration to include the cheap transformer. This ensures that TypeScript files are compiled with necessary transformations for cheap.

```javascript

import { defineConfig } from 'vite';
import typescript from '@rollup/plugin-typescript';
import * as transformer from '@libmedia/cheap/build/transformer';

export default defineConfig({
  ...
  plugins: [
    typescript({
      // configure the tsconfig.json configuration file used
      // setting of "include" must to include the files need to compile
      tsconfig: './tsconfig.json',
      ...
      transformers: {
        before: [
          {
            type: 'program',
            factory: (program) => {
              return transformer.before(program)
            }
          }
        ]
      },
      ...
    })
  ],
});

```

--------------------------------

### Smart Pointer and Struct Utilities

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Functions for creating and destroying struct instances and smart pointers.

```APIDOC
## Smart Pointer and Struct Utilities

### Description
Functions to manage object lifecycles and smart pointer references.

### Functions
- **make<T>()**: Create a struct instance.
- **unmake<T>(target)**: Destroy a struct instance.
- **make_shared_ptr<T>()**: Create a SharedPtr smart pointer with optional initializers and deleters.
```

--------------------------------

### SharedPtr Smart Pointer Creation

Source: https://github.com/zhaohappy/cheap/blob/master/README.md

Demonstrates creating SharedPtr instances for custom structs and primitive types, with options for initial data and custom destructors.

```typescript
@struct
class MyStruct {
  a: int8
}

// 无参构造
const p0 = make_shared_ptr<MyStruct>()
const p1 = make_shared_ptr<int32>()
// 带初始化数据的构造
const p2 = make_shared_ptr<MyStruct>({a: 0})
const p3 = make_shared_ptr<int32>(43)

function freeMyStruct(p: pointer<MyStruct>) {
  free(p)
}
// 带自定义析构函数的构造，不传使用默认析构只会 free 结构体自己的内存
const p4 = make_shared_ptr<MyStruct>(freeMyStruct)

// 带初始化数据和自定义析构函数的构造
const p5 = make_shared_ptr<MyStruct>({a: 0}, freeMyStruct)

// 访问原始指针的属性
console.log(p5.a)
// 获取原始指针的属性地址
console.log(addressof(p5.a))
```

--------------------------------

### Define and Use Structs in TypeScript

Source: https://context7.com/zhaohappy/cheap/llms.txt

Demonstrates defining C-compatible structs with decorators and using them to create, access, and modify data. Ensure to clean up memory with unmake when done.

```typescript
import { make, unmake, addressof, sizeof } from '@libmedia/cheap'

// Define a struct using the @struct decorator
@struct
class Point {
  x: int32
  y: int32
}

@struct
class Rectangle {
  topLeft: Point           // Nested struct
  width: uint32
  height: uint32
  color: pointer<uint8>    // Pointer to color data
  vertices: array<int32, 4> // Fixed-size array
}

// Create a struct instance with initialization
const rect = make<Rectangle>({
  topLeft: { x: 10, y: 20 },
  width: 100,
  height: 50
})

// Access and modify properties
rect.topLeft.x = 15
rect.width = 200
console.log(rect.topLeft.y) // Output: 20

// Get struct size for memory operations
const size = sizeof(Rectangle)
console.log(`Rectangle size: ${size} bytes`)

// Clean up when done
unmake(rect)
```

--------------------------------

### Configure Webpack Plugin for Cheap

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Utilize the CheapPlugin within your webpack configuration for browser or node environments. This plugin assists in integrating cheap's features during the webpack build process.

```javascript
const path = require('path');
const CheapPlugin = require('@libmedia/cheap/build/webpack/CheapPlugin');
module.exports = (env) => {
  return {
    ...
    rules: [
      {
        test: /\.ts?$/,
        use: [
          {
            loader: 'ts-loader'
          }
        ]
      }
    ],
    plugins: [
      new CheapPlugin({
        // 'browser' | 'node'
        env: 'browser',
        // project root directory, here means webpack.config.js is under the project root directory
        projectPath: __dirname,
        // can add macro definition here
        defined: {

        }
      })
    ]
  }
}
```

--------------------------------

### SharedPtr Smart Pointer

Source: https://github.com/zhaohappy/cheap/blob/master/README.md

Details on the SharedPtr smart pointer, its usage, methods, and compatibility.

```APIDOC
## SharedPtr Smart Pointer

### Description
SharedPtr is a reference-counted smart pointer that automatically manages memory, reducing the risk of memory leaks. It relies on the `FinalizationRegistry` API and is not polyfillable.

### Compatibility

| Environment | Version |
| ----------- | ----------- |
| Chrome | 84+ |
| Firefox | 79+ |
| Safari | 14.1+ |
| Safari iOS | 14.5+ |
| Node.js | 14.6.0+ |
| Deno | 1.0+ |

> Smart pointers are JavaScript objects passed by reference.

### Usage

```typescript
@struct
class MyStruct {
  a: int8
}

// Constructor without arguments
const p0 = make_shared_ptr<MyStruct>()
const p1 = make_shared_ptr<int32>()

// Constructor with initial data
const p2 = make_shared_ptr<MyStruct>({a: 0})
const p3 = make_shared_ptr<int32>(43)

function freeMyStruct(p: pointer<MyStruct>) {
  free(p)
}

// Constructor with custom destructor (default is `free`)
const p4 = make_shared_ptr<MyStruct>(freeMyStruct)

// Constructor with initial data and custom destructor
const p5 = make_shared_ptr<MyStruct>({a: 0}, freeMyStruct)

// Accessing struct members
console.log(p5.a)

// Getting the address of a member
console.log(addressof(p5.a))
```

### Methods

- **`get(): pointer<T>`**: Returns the raw pointer.
- **`reset(value?: pointer<T>): void`**: Resets the pointer to a new value or null.
- **`unique(): boolean`**: Returns `true` if the pointer has only one reference.
- **`useCount(): int32`**: Returns the current reference count.
- **`has(): boolean`**: Returns `true` if the pointer is not null.
- **`transferable(): SharedPtrTransferable<T>`**: Makes the smart pointer transferable.
- **`clone(): SharedPtr<T>`**: Clones the smart pointer, increasing the reference count.

### Passing Smart Pointers Between Threads

Due to data copying between workers, passing smart pointers directly between threads can lead to unexpected behavior. For frequently passed data structures between threads, it is recommended to use raw pointers and manage them with an object pool.

```typescript
import { createThreadFromFunction, deTransferableSharedPtr } from '@libmedia/cheap'

@struct
class MyStruct {
  a: int8
}

function worker(t: SharedPtrTransferable<MyStruct>) {
  const p = deTransferableSharedPtr(t)
  console.log(p.a)
}

const p = make_shared_ptr<MyStruct>()
const transfer = p.transferable()
const thread = await createThreadFromFunction(worker).transfer(transfer.buffer).run(transfer)
```
```

--------------------------------

### Worker Entry Point

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Defines the entry point for a worker thread. This file imports a task and uses `runThread` to execute it.

```javascript
import task from './task'
import runThread from '@libmedia/cheap/runThread'
runThread(task)
```

--------------------------------

### Implement Condition Variables

Source: https://context7.com/zhaohappy/cheap/llms.txt

Shows how to use Condition Variables with Mutexes to manage producer-consumer queues, including blocking waits and asynchronous timed waits.

```typescript
import { Mutex, Cond } from '@libmedia/cheap'
import * as mutex from '@libmedia/cheap/thread/mutex'
import * as cond from '@libmedia/cheap/thread/cond'

@struct
class MessageQueue {
  head: int32
  tail: int32
  count: int32
  capacity: int32
  data: pointer<int32>
  lock: Mutex
  notEmpty: Cond
  notFull: Cond
}

// Initialize the queue
const queue = reinterpret_cast<pointer<MessageQueue>>(malloc(sizeof(MessageQueue)))
queue.head = 0
queue.tail = 0
queue.count = 0
queue.capacity = 100
queue.data = reinterpret_cast<pointer<int32>>(malloc(100 * sizeof(int32)))
mutex.init(addressof(queue.lock))
cond.init(addressof(queue.notEmpty))
cond.init(addressof(queue.notFull))

// Producer (worker thread)
function produce(q: pointer<MessageQueue>, value: int32) {
  mutex.lock(addressof(q.lock))

  // Wait while queue is full
  while (q.count >= q.capacity) {
    cond.wait(addressof(q.notFull), addressof(q.lock))
  }

  // Add item to queue
  q.data[q.tail] = value
  q.tail = (q.tail + 1) % q.capacity
  q.count++

  // Signal that queue is not empty
  cond.signal(addressof(q.notEmpty))
  mutex.unlock(addressof(q.lock))
}

// Consumer (worker thread)
function consume(q: pointer<MessageQueue>): int32 {
  mutex.lock(addressof(q.lock))

  // Wait while queue is empty
  while (q.count === 0) {
    cond.wait(addressof(q.notEmpty), addressof(q.lock))
  }

  // Remove item from queue
  const value = q.data[q.head]
  q.head = (q.head + 1) % q.capacity
  q.count--

  // Signal that queue is not full
  cond.signal(addressof(q.notFull))
  mutex.unlock(addressof(q.lock))

  return value
}

// Async consumer for main thread with timeout
async function consumeAsync(q: pointer<MessageQueue>, timeoutMs: int32): Promise<int32 | null> {
  await mutex.lockAsync(addressof(q.lock))

  if (q.count === 0) {
    const result = await cond.timedwaitAsync(addressof(q.notEmpty), addressof(q.lock), timeoutMs)
    if (result === 110) {  // ETIMEDOUT
      mutex.unlock(addressof(q.lock))
      return null
    }
  }

  const value = q.data[q.head]
  q.head = (q.head + 1) % q.capacity
  q.count--

  cond.signal(addressof(q.notFull))
  mutex.unlock(addressof(q.lock))

  return value
}
```

--------------------------------

### Initialize Mutex

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Initializes a Mutex. Ensure the Mutex is properly initialized before use.

```typescript
/**
 * init Mutex
 * 
 * @param mutex 
 */
function init(mutex: pointer<Mutex>): int32
```

--------------------------------

### Implement Resource Pool with Semaphores

Source: https://context7.com/zhaohappy/cheap/llms.txt

Use semaphores to manage access to a fixed pool of resources. Requires initialization with a resource count and proper cleanup.

```typescript
import { Sem } from '@libmedia/cheap'
import * as semaphore from '@libmedia/cheap/thread/semaphore'

@struct
class ResourcePool {
  available: Sem
  resources: array<pointer<void>, 10>
  resourceIndex: int32
  lock: Mutex
}

// Initialize semaphore with count of available resources
const pool = reinterpret_cast<pointer<ResourcePool>>(malloc(sizeof(ResourcePool)))
semaphore.init(addressof(pool.available), 10)  // 10 resources available
pool.resourceIndex = 10

// Acquire a resource (blocks until available)
function acquireResource(p: pointer<ResourcePool>): pointer<void> {
  // Wait for available resource
  semaphore.wait(addressof(p.available))

  // Get resource from pool (protected by implicit synchronization)
  const resource = p.resources[--p.resourceIndex]
  return resource
}

// Release a resource back to the pool
function releaseResource(p: pointer<ResourcePool>, resource: pointer<void>) {
  p.resources[p.resourceIndex++] = resource
  semaphore.post(addressof(p.available))  // Signal resource available
}

// Try to acquire without blocking
function tryAcquireResource(p: pointer<ResourcePool>): pointer<void> | null {
  const result = semaphore.tryWait(addressof(p.available))
  if (result === 0) {
    return p.resources[--p.resourceIndex]
  }
  return null  // No resources available
}

// Async acquire with timeout (for main thread)
async function acquireResourceAsync(p: pointer<ResourcePool>, timeoutMs: int32): Promise<pointer<void> | null> {
  const result = await semaphore.timedWaitAsync(addressof(p.available), timeoutMs)
  if (result === 0) {
    return p.resources[--p.resourceIndex]
  }
  return null  // Timeout
}

// Get current semaphore value
const currentAvailable = semaphore.get(addressof(pool.available))
console.log(`Resources available: ${currentAvailable}`)

// Cleanup
semaphore.destroy(addressof(pool.available))
free(pool)
```

--------------------------------

### Implement Mutex Synchronization

Source: https://context7.com/zhaohappy/cheap/llms.txt

Demonstrates using Mutexes for thread-safe access to shared memory, including synchronous blocking, asynchronous non-blocking, and try-lock patterns.

```typescript
import { Mutex } from '@libmedia/cheap'
import * as mutex from '@libmedia/cheap/thread/mutex'

@struct
class SharedCounter {
  value: int32
  lock: Mutex
}

// Allocate shared counter in heap memory
const counter = reinterpret_cast<pointer<SharedCounter>>(malloc(sizeof(SharedCounter)))
counter.value = 0
mutex.init(addressof(counter.lock))

// Worker thread function
async function incrementCounter(counterPtr: pointer<SharedCounter>, times: number) {
  for (let i = 0; i < times; i++) {
    // Synchronous lock (blocks the worker thread)
    mutex.lock(addressof(counterPtr.lock))
    counterPtr.value++
    mutex.unlock(addressof(counterPtr.lock))
  }
}

// Main thread function (use async to avoid blocking)
async function readCounter(counterPtr: pointer<SharedCounter>): Promise<number> {
  // Async lock (non-blocking, suitable for main thread)
  await mutex.lockAsync(addressof(counterPtr.lock))
  const value = counterPtr.value
  mutex.unlock(addressof(counterPtr.lock))
  return value
}

// Try lock without blocking
function tryIncrementCounter(counterPtr: pointer<SharedCounter>): boolean {
  const result = mutex.tryLock(addressof(counterPtr.lock))
  if (result === 0) {  // Successfully acquired lock
    counterPtr.value++
    mutex.unlock(addressof(counterPtr.lock))
    return true
  }
  return false  // Lock was held by another thread
}

// Cleanup
mutex.destroy(addressof(counter.lock))
free(counter)
```

--------------------------------

### Load and Execute WebAssembly Modules

Source: https://context7.com/zhaohappy/cheap/llms.txt

Use WebAssemblyRunner to manage WASM module lifecycle, custom imports, and multi-threaded execution.

```typescript
import { WebAssemblyRunner, compileResource } from '@libmedia/cheap'

// Compile WebAssembly resource (can be cached in IndexedDB)
const resource = await compileResource({
  source: 'https://example.com/mymodule.wasm'
  // Or from ArrayBuffer:
  // source: wasmArrayBuffer
})

// Create runner with custom imports
const runner = new WebAssemblyRunner(resource, {
  imports: {
    env: {
      // Custom JavaScript functions callable from WebAssembly
      log_message: (msgPtr: pointer<char>) => {
        const message = readCString(msgPtr)
        console.log(`[WASM]: ${message}`)
      },
      get_time: () => Date.now()
    }
  }
})

// Run the module (initializes runtime)
await runner.run()

// Call exported WebAssembly functions
// Arguments must be numbers or bigints; use pointers for complex data
const result = runner.invoke<number>('process_data', dataPointer, dataLength)

// For async operations (requires JSPI support)
const asyncResult = await runner.invokeAsync<number>('async_process', inputPtr)

// Access the WebAssembly instance directly
const instance = runner.getInstance()
const exports = instance.exports

// Multi-threaded WebAssembly (creates child threads via pthread)
await runner.run({}, 4)  // Initialize with thread pool of 4
await runner.childThreadsReady()  // Wait for all child threads

// Cleanup
runner.destroy()
```

--------------------------------

### Pointer and Type Utilities

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Functions for address retrieval, pointer access, and type size calculation.

```typescript
/**
 * & Get address
 * Note that you can only fetch the memory address on cheap, but cannot fetch the address on the js stack or heap.
 */
function addressof<T>(type: T): T extends any[] ? pointer<UnwrapArray<T>> : pointer<T>

/**
 * * access pointer
 */
function accessof<T extends (IsBuiltinType<T> extends true ? never : anyptr)>(pointer: T): UnwrapPointer<T>

/**
 * Returns the size occupied by type
 */
function sizeof(type: any): size
```

--------------------------------

### Struct Instance Management

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Functions for creating and destroying struct instances.

```typescript
/**
 * Create a struct instance
 */
function make<T extends {}>(): T
function make<T extends {}>(init: Partial<SetOmitFunctions<T>>): T

/**
 * Destroy a struct instance
 * 
 * @param target 
 */
function unmake<T extends Object>(target: T): void
```

--------------------------------

### Initialize Semaphore

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Initializes a Semaphore with a given initial value.

```typescript
/**
 * init Sem
 * 
 * @param sem 
 * @param value
 */
function init(sem: pointer<Sem>, value: uint32): int32
```

--------------------------------

### Debugging and Utility Functions

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

General purpose utilities for debugging and memory inspection.

```APIDOC
## Debugging and Utility Functions

### Description
Utilities for debugging, memory inspection, and macro definitions.

### Functions
- **assert(condition, msg?)**: Pause execution in debug mode if condition is false.
- **addressof<T>(type)**: Get the memory address of a type.
- **accessof<T>(pointer)**: Access the value pointed to by a pointer.
- **sizeof(type)**: Return the size occupied by a type.
- **defined<T>(def)**: Replace with the value defined by a macro.
```

--------------------------------

### Configure Webpack for Cheap Transformer

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Integrate the cheap transformer into your webpack configuration using ts-loader. This allows webpack to process TypeScript files with cheap's custom transformations.

```javascript
const path = require('path');
const transformer = require('@libmedia/cheap/build/transformer');
module.exports = (env) => {
  return {
    module: {
      rules: [
        {
          test: /\.ts?$/,
          use: [
            {
              loader: 'ts-loader',
              options: {
                ...
                getCustomTransformers: function(program) {
                  return {
                    before: [transformer.before(program)]
                  }
                },
                ...
              }
            }
          ]
        }
      ],
    }
  }
}
```

--------------------------------

### Semaphore Operations

Source: https://github.com/zhaohappy/cheap/blob/master/README.md

Functions for initializing, posting, waiting, and trying/timed waiting on semaphores.

```APIDOC
## Semaphore Operations

### Description
Provides functions for managing semaphores for thread synchronization.

### Initialize Semaphore

#### Method
`function init(sem: pointer<Sem>, value: uint32): int32`

#### Description
Initializes a semaphore with a given initial value.

### Post Semaphore

#### Method
`function post(sem: pointer<Sem>): int32`

#### Description
Increments the semaphore's value, potentially waking up a waiting thread.

### Wait on Semaphore

#### Method
`function wait(sem: pointer<Sem>): int32`

#### Description
Decrements the semaphore's value, blocking if the value is zero.

### Try Wait on Semaphore

#### Method
`function tryWait(sem: pointer<Sem>): int32`

#### Description
Attempts to decrement the semaphore's value without blocking. Returns immediately if the value is zero.

### Timed Wait on Semaphore

#### Method
`function timedWait(sem: pointer<Sem>, timeout: int32): int32`

#### Description
Attempts to decrement the semaphore's value, blocking for a specified timeout period.

### Async Wait on Semaphore

#### Method
`async function waitAsync(sem: pointer<Sem>): Promise<int32>`

#### Description
Asynchronously decrements the semaphore's value, blocking if the value is zero.

### Async Timed Wait on Semaphore

#### Method
`async function timedWaitAsync(sem: pointer<Sem>, timeout: int32): Promise<int32>`

#### Description
Asynchronously attempts to decrement the semaphore's value, blocking for a specified timeout period.
```

--------------------------------

### make_shared_ptr

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Creates a new SharedPtr instance for a given type, optionally with initial data and a custom destructor.

```APIDOC
## make_shared_ptr<T>

### Description
Creates a new sharable smart pointer. If a custom destructor is provided, it will be called when the pointer is freed.

### Parameters
- **T** (Type) - The type of the structure to manage.
- **data** (T) - Optional - Initial data for the structure.
- **destructor** (Function) - Optional - Custom function to handle memory cleanup.

### Request Example
const p = make_shared_ptr<MyStruct>({a: 0}, freeMyStruct);
```

--------------------------------

### Configure Rollup for Cheap Transformer

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Add the cheap transformer to your Rollup configuration using the typescript plugin. This enables Rollup to process TypeScript files with cheap's specific transformations.

```javascript

import typescript from '@rollup/plugin-typescript';
import * as transformer from '@libmedia/cheap/build/transformer'

export default {
  ...
  plugins: [
    typescript({
      // configure the tsconfig.json configuration file used
      // setting of "include" must to include the files need to compile
      tsconfig: './tsconfig.json',
      ...
      transformers: {
        before: [
          {
            type: 'program',
            factory: (program) => {
              return transformer.before(program)
            }
          }
        ]
      },
      ...
    }),
  ]
};


```

--------------------------------

### Thread Creation and Management

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Functions for creating threads from various entities and managing their lifecycle.

```APIDOC
## createThreadFromClass

### Description
Creates a thread from a class and returns a handle to call class member functions asynchronously.

### Parameters
- **entity** (new (...args: U) => T) - Required - The class to instantiate in the thread.
- **options** (ThreadOptions) - Optional - Configuration options for the thread.

### Response
- **run** (Function) - Returns a Promise resolving to a Thread handle.
- **transfer** (Function) - Configures transferable objects for the thread.

## createThreadFromFunction

### Description
Creates a thread from a function that runs immediately and exits upon completion.

### Parameters
- **entity** ((...args: T) => void) - Required - The function to execute.
- **options** (ThreadOptions) - Optional - Configuration options for the thread.

## createThreadFromModule

### Description
Creates a thread from a module, allowing asynchronous calls to module methods.

### Parameters
- **entity** (Object) - Required - The module to run in the thread.

## closeThread

### Description
Forcefully terminates a thread. Note: May cause memory leaks; use joinThread instead.

### Parameters
- **thread** (Thread) - Required - The thread handle to terminate.

## joinThread

### Description
Waits for a thread to exit and retrieves its return value.

### Parameters
- **thread** (Thread) - Required - The thread handle to wait for.
```

--------------------------------

### SharedPtr Interface Methods

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Methods available on the SharedPtr instance for managing the underlying raw pointer and reference counting.

```APIDOC
## SharedPtr<T> Methods

### Methods
- **get()** - Returns the raw pointer.
- **reset(value?: pointer<T>)** - Resets the raw pointer.
- **unique()** - Returns true if the pointer has only one reference.
- **useCount()** - Returns the current reference count.
- **has()** - Returns true if the pointer exists.
- **transferable()** - Converts the smart pointer to a transferable object for cross-thread communication.
- **clone()** - Increases the reference count and returns a new SharedPtr instance.
```

--------------------------------

### Debugging and Macro Utilities

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Utilities for assertions and macro definitions.

```typescript
/**
 * assert
 * in debug mode will pause here if assert failed when opening the browser's console.
 * in release mode, assert will be delete in code
 * 
 * @param condition
 * @param msg Error message printed when assert failed
 */
function assert(condition: any, msg?: string): void

/**
 * use the macro definition, it will be replaced by the value defined by the macro.
 * 
 * @param def 
 */
function defined<T>(def: T): T
```

--------------------------------

### SharedPtr Smart Pointer Creation

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Overloaded functions for creating SharedPtr instances with optional deleters and initializers.

```typescript
/**
 * Create SharedPtr Smart Pointer
 */
function make_shared_ptr<T extends BuiltinType>(): SharedPtr<T>
function make_shared_ptr<T extends BuiltinType>(deleter: deleter<T>): SharedPtr<T>
function make_shared_ptr<T extends BuiltinType>(value: T): SharedPtr<T>
function make_shared_ptr<T extends BuiltinType>(value: pointer<T>): SharedPtr<T>
function make_shared_ptr<T extends BuiltinType>(value: T, deleter: deleter<T>): SharedPtr<T>
function make_shared_ptr<T extends BuiltinType>(value: pointer<T>, deleter: deleter<T>): SharedPtr<T>
function make_shared_ptr<T extends {}>(): SharedPtr<T>
function make_shared_ptr<T extends {}>(deleter: deleter<T>): SharedPtr<T>
function make_shared_ptr<T extends {}>(init: Partial<SetOmitFunctions<T>>): SharedPtr<T>
function make_shared_ptr<T extends {}>(init: pointer<T>): SharedPtr<T>
function make_shared_ptr<T extends {}>(init: T): SharedPtr<T>
function make_shared_ptr<T extends {}>(init: pointer<T>, deleter: deleter<T>): SharedPtr<T>
function make_shared_ptr<T extends {}>(init: T, deleter: deleter<T>): SharedPtr<T>
function make_shared_ptr<T extends {}>(init: Partial<SetOmitFunctions<T>>, deleter: deleter<T>): SharedPtr<T>
```

--------------------------------

### Create and Manage Threads

Source: https://context7.com/zhaohappy/cheap/llms.txt

Implement multi-threading using classes, functions, or modules. Threads share memory via SharedArrayBuffer and support data transfer.

```typescript
import {
  createThreadFromClass,
  createThreadFromFunction,
  createThreadFromModule,
  joinThread,
  closeThread
} from '@libmedia/cheap'

// === Thread from Class ===
// Define the worker class in a separate file (worker-class.ts)
export class ImageProcessor {
  private width: number
  private height: number

  constructor(width: number, height: number) {
    this.width = width
    this.height = height
  }

  async processPixels(dataPtr: pointer<uint8>): Promise<number> {
    // Process image data in worker thread
    for (let i = 0; i < this.width * this.height * 4; i++) {
      dataPtr[i] = static_cast<uint8>(255 - dataPtr[i])  // Invert colors
    }
    return this.width * this.height
  }
}

// Main thread usage
import { ImageProcessor } from './worker-class'
import workerUrl from './worker-entry?worker'

const thread = await createThreadFromClass(ImageProcessor, workerUrl).run(1920, 1080)
const pixelData = malloc(1920 * 1080 * 4)
const processedCount = await thread.processPixels(pixelData)
console.log(`Processed ${processedCount} pixels`)
closeThread(thread)

// === Thread from Function ===
function computeTask(iterations: number, resultPtr: pointer<int32>): number {
  let sum = 0
  for (let i = 0; i < iterations; i++) {
    sum += i
  }
  accessof(resultPtr) <- static_cast<int32>(sum)
  return sum
}

const resultPtr = reinterpret_cast<pointer<int32>>(malloc(sizeof(int32)))
const funcThread = await createThreadFromFunction(computeTask, workerUrl).run(1000000, resultPtr)
const result = await joinThread<number>(funcThread)
console.log(`Computation result: ${result}`)

// === Thread with Transferable Data ===
const largeBuffer = new ArrayBuffer(1024 * 1024)
const transferThread = await createThreadFromFunction(processBuffer, workerUrl)
  .transfer(largeBuffer)  // Transfer ownership of buffer
  .run(largeBuffer)
```

--------------------------------

### Create Thread from Module

Source: https://github.com/zhaohappy/cheap/blob/master/README_en.md

Creates a thread from a module, returning a handle to asynchronously call methods within the module.

```typescript
function createThreadFromModule<T extends Object>(entity: T, options?: ThreadOptions): {
  run: () => Promise<Thread<T>>
}
```

--------------------------------

### Mutex Initialization and Management

Source: https://github.com/zhaohappy/cheap/blob/master/README.md

Functions for initializing, locking, unlocking, and destroying mutexes. The lock function supports a spin option for busy-waiting.

```typescript
/**
 * 初始化锁
 * 
 * @param mutex 
 */
function init(mutex: pointer<Mutex>): int32
```

```typescript
/**
 * 加锁
 * 
 * @param mutex 
 * @param spin 是否自旋
 */
function lock(mutex: pointer<Mutex>, spin: boolean = false): int32
```

```typescript
/**
 * 异步加锁
 * 
 * @param mutex
 */
async function lockAsync(mutex: pointer<Mutex>): Promise<int32>
```

```typescript
/**
 * 释放锁
 * 
 * @param mutex 
 */
function unlock(mutex: pointer<Mutex>): int32
```

```typescript
/**
 * 销毁锁
 * 
 * @param mutex 
 * @returns 
 */
function destroy(mutex: pointer<Mutex>): int32
```
Tokens:
Raw