dymokomi/luce-base
Source of release 0.42.0
0.42.0 / src / std / interop / transfer.lucb
#==============================================================================================
#
# transfer - Uniquely owned cross-thread messages
#
# DESCRIPTION:
# A `Packet` is a uniquely owned message outside either thread's ARC graph; a `Transfer`
# is the deep-copy policy, and a `Reply` carries a worker's result or failure.
#
#==============================================================================================
## A uniquely owned message outside either thread's ARC graph. Copies borrow;
## passing a packet into a queue transfers its release obligation. Its disposer
## must work on either thread and must not access thread-bound owners/allocators.
pub struct Packet[T]:
## The message value.
pub let value: T
let storage: void*? = none
let dispose: (func(void*) -> unit)? = none
## A packet owning `value`, released through `dispose`.
pub func init(value: T, storage: void*? = none, dispose: (func(void*) -> unit)? = none):
self.value = value
self.storage = storage
self.dispose = dispose
## Dispose the packet's storage.
pub func release():
if let storage = self.storage:
(self.dispose else trap("a packet has storage without a disposer"))(storage)
## Deep-copy policy supplied by the native library for a wire value. All borrowed
## members must point into the returned packet or immutable process-lifetime data.
## A policy must never smuggle an ARC owner, checked view or callback across threads.
pub struct Transfer[T]:
## The library's deep-copy of a wire value into a packet.
pub let copy: func(T) -> Packet[T]!
## For pointer-free scalar/record values only. Text/spans need a deep copy.
pub static func plain() -> Transfer[T]:
return Transfer[T](Transfer[T].copy_plain)
static func copy_plain(value: T) -> Packet[T]!:
return Packet[T](value)
struct PacketBytes:
var bytes: u8[]
static func drop(raw: void*):
let storage = (PacketBytes*)raw
free(storage.bytes) in memory.heap
free(storage) in memory.heap
static func copy(value: const u8[]) -> Packet[const u8[]]!:
let bytes = try new u8[value.length] --- in memory.heap
errdefer free(bytes) in memory.heap
memory.copy(bytes, value, value.length)
let storage = try new PacketBytes(bytes) in memory.heap
return Packet[const u8[]](bytes, (void*)storage, PacketBytes.drop)
static func text(value: str) -> Packet[str]!:
let packet = try PacketBytes.copy(value.bytes)
return Packet[str]((str)packet.value, packet.storage, packet.dispose)
## The deep-copy policy for `str`.
pub let text_transfer: Transfer[str] = Transfer[str](PacketBytes.text)
## The deep-copy policy for byte spans.
pub let bytes_transfer: Transfer[const u8[]] = Transfer[const u8[]](PacketBytes.copy)
## A reply owns its successful packet or its copied failure text. get borrows;
## release is required whether the caller handles success or failure.
pub struct Reply[T]:
let result: Packet[T]?
## The failure code, or `package(0)` on success.
pub let code: ErrorCode
let message: Packet[str]?
## A successful reply carrying `value`.
pub static func success(value: Packet[T]) -> Reply[T]:
return Reply[T](value, no_error, none)
## A failed reply with `code` and a copied `message`.
pub static func failure(code: ErrorCode, message: str) -> Reply[T]:
let copy = text_transfer.copy(message) catch failure:
return Reply[T](none, memory.exhausted, Packet[str]("out of memory copying a worker failure"))
return Reply[T](none, code, copy)
## Whether the reply succeeded.
pub func is_success() -> bool:
return self.message == none
## The success value, or the failure as an error.
pub func get() -> T!:
if let message = self.message:
error(self.code, message.value)
return (self.result else trap("a worker reply has no result")).value
## Release the reply's owned value or message.
pub func release():
if let result = self.result:
result.release()
if let message = self.message:
message.release()