promise 类详解

promise 类详解（来自 vine.promises）

1. 作用

promise 是一种异步编程工具，用于表示“未来某个时刻可用的值”或“延迟执行的操作”。它允许你注册回调（then）、错误处理（on_error）、链式调用等，类似于 JavaScript 的 Promise，但更灵活，支持懒执行和回调链。

2. 主要特性

• 延迟执行：只有调用 promise() 时才真正执行。
• 链式回调：通过 then() 方法注册后续操作。
• 错误处理：通过 on_error 或 throw() 处理异常。
• 取消：通过 cancel() 取消 promise 和所有回调。
• 弱引用支持：可选，避免内存泄漏。
• 回调链：每个 promise 可以有多个回调，按顺序执行。

3. 关键方法说明

• __init__：初始化，支持传入函数、参数、回调、错误处理等。
• __call__：执行 promise，触发回调链。
• then(callback)：注册回调，返回新的 promise。
• throw(exc)：触发异常，调用错误处理和回调链的异常处理。
• cancel()：取消 promise 和所有回调。
• on_error：错误处理回调。
• weak：是否使用弱引用保存函数。

4. 代码示例

基本用法

from vine import promise

def add(x, y):
    print(f"add({x}, {y}) called")
    return x + y

def show_result(result):
    print("Result:", result)

def show_error(exc):
    print("Error:", exc)

# 创建一个 promise，延迟执行 add(2, 3)
p = promise(add, (2, 3), on_error=show_error)

# 注册回调
p.then(show_result)

# 执行 promise（实际调用 add(2, 3)，并将结果传给 show_result）
p()
# 输出:
# add(2, 3) called
# Result: 5

# 抛出异常
def fail():
    raise ValueError("fail!")

p2 = promise(fail, on_error=show_error)
p2.then(show_result)
p2()
# 输出:
# Error: fail!

链式调用

from vine import promise

def step1(x):
    print("step1:", x)
    return x + 1

def step2(y):
    print("step2:", y)
    return y * 2

def step3(z):
    print("step3:", z)
    return z - 3

p = promise(step1, (10,))
p2 = p.then(step2).then(step3)
p()
# 输出:
# step1: 10
# step2: 11
# step3: 22

错误处理链

from vine import promise

def will_fail(x):
    raise RuntimeError("bad stuff")

def on_error(exc):
    print("Caught error:", exc)

p = promise(will_fail, (42,), on_error=on_error)
p.then(lambda x: print("Should not run:", x))
p()
# 输出:
# Caught error: bad stuff

取消 promise

from vine import promise

def myfunc():
    print("Should not run")

p = promise(myfunc)
p.cancel()
p()  # 不会执行 myfunc

5. 总结

• promise 类实现了异步/延迟执行、回调链、错误处理和取消等功能。
• 用法类似 JavaScript Promise，但更灵活，适合 Python 回调式异步场景。
• 支持链式调用和多回调，适合复杂异步流程控制。

如需更深入理解，可结合源码和实际项目场景进行调试和扩展。