한국어 | English

Reference index

05. Errors

This category is this reference's counterpart to core's result-enum-family table — it documents the shared exception hierarchy and the seven typed exceptions every submit/request/recv/event/ close/bind/connect/config-failing API throws (Sockets/Messaging/Eventing/Core categories). The exact signatures are owned by contracts/errors/.

---

Typed exception family

Each API family throws its own typed exception carrying a typed result enum, rather than one shared exception type — a caller catches the specific type (or the shared ZlinkException base) and calls .getResult(). The hierarchy is a Java sealed class: ZlinkException (public, abstract sealed, permits TypedZlinkException) → TypedZlinkException (package-private, abstract sealed, not directly referenceable by name from application code) → each concrete exception below (public final).

Exception	Result enum	Thrown by	Values
ZlinkSubmitException	SubmitResult (Sockets category)	send/publish/request-submit APIs	BACKPRESSURED(1, ordinary control flow), NOT_CONNECTED(2), NOT_FOUND(3), TERMINATED(4), INVALID_HANDLE(5), INVALID_ARGUMENT(6), NOT_SUPPORTED(7), INVALID_STATE(8), THREAD_VIOLATION(9), OUT_OF_MEMORY(10), SEQ_EXHAUSTED(11), INTERNAL_ERROR(12), NOT_ADMITTED(13, ordinary control flow)
ZlinkRequestException	RequestResult (Sockets category)	submit_sync() or submit() terminal request failure	TIMED_OUT(101), NOT_FOUND(102), TERMINATED(103), PROTOCOL_ERROR(104), INTERNAL_ERROR(105), REJECTED(106), CONFLICT(107), BUSY(108), NOT_CONNECTED(109), INVALID_ARGUMENT(110), INVALID_STATE(111), NOT_SUPPORTED(112), BACKPRESSURED(113)
ZlinkRecvException	RecvResult (Sockets category)	recv-family APIs	NO_DATA(201), BUSY(202), TERMINATED(203), INVALID_HANDLE(204), NOT_SUPPORTED(205), INTERNAL_ERROR(206)
ZlinkHandlerException	HandlerResult	retained result family; current public completion/event delivery has no registered handler	INVALID_ARGUMENT(301), BUSY(302), NOT_SUPPORTED(303), DEADLOCK(304), INVALID_HANDLE(305), INTERNAL_ERROR(306)
ZlinkCloseException	CloseResult	close() paths, Context.shutdown()	BUSY(401), SHUTDOWN(402), INVALID_HANDLE(403), INTERNAL_ERROR(404)
ZlinkBindException	BindResult	Socket.bind(...)	INVALID_ARGUMENT(501), ADDR_IN_USE(502), NOT_SUPPORTED(503), INVALID_HANDLE(504), INTERNAL_ERROR(505)
ZlinkConnectException	ConnectResult	connect/unbind/disconnect/disconnectRid	INVALID_ARGUMENT(601), NOT_SUPPORTED(602), INVALID_HANDLE(603), INTERNAL_ERROR(604), NOT_FOUND(605), CONFLICT(606), BUSY(607)
ZlinkConfigException	ConfigResult	every socket/context option getter/setter	INVALID_HANDLE(701), INVALID_ARGUMENT(702), NOT_SUPPORTED(703), INTERNAL_ERROR(704), INVALID_STATE(705), NOT_FOUND(706), CONFLICT(707), BUFFER_TOO_SMALL(708), BUSY(709)

What each value family actually means. SubmitResult's BACKPRESSURED/NOT_CONNECTED/ NOT_FOUND/NOT_ADMITTED are ordinary execution flow, not exceptional failures — a caller that treats every non-OK submit result the same way loses the distinction between "retry is reasonable" and "this submit will never succeed as constructed." INVALID_STATE covers a stale handle or a closed receive/connection state. HandlerResult remains part of the result model, but current public send/request terminals and pull-event surfaces do not produce it.

---

ZlinkException

The public abstract base every typed exception derives from (through the package-private intermediate TypedZlinkException).

try {
    dealer.send().message(part).submit();
} catch (ZlinkSubmitException ex) {
    if (ex.getResult() == SubmitResult.BACKPRESSURED) {
        // ordinary control flow, not a real failure
    }
}

Options. Constructors are protected — the public entry point for constructing any typed exception is that exception's own public constructor taking its result enum (ZlinkSubmitException(SubmitResult), etc.), or the same constructor plus an explicit nativeErrno.

Member	Meaning
getCode()	int, the zlink result code that classifies the failure
getNativeErrno()	int, the underlying native errno, or 0 when none
fromLastError(ErrorCategory)	static factory; reads the current native errno and builds the exception of the given category
fromErrno(ErrorCategory, int errno)	static factory; builds the correctly-typed exception from the errno collected when the native call returned and an ErrorCategory (CONFIG/BIND/CONNECT/CLOSE/HANDLER/RECV/REQUEST/SUBMIT)

Completion result. N/A — this is the exception hierarchy itself. TypedZlinkException (the intermediate sealed class) is package-private — application code can catch/reference ZlinkException or a specific concrete subclass, but cannot name TypedZlinkException directly.

When to use. Catch the specific typed exception (ZlinkSubmitException, etc.) to call its enum-typed getResult(), or catch the shared ZlinkException base when only getCode()/ getNativeErrno() are needed generically across exception types. No-data and transient back-pressure are never reported as an ordinary exception — see the Sockets/Messaging categories' boolean-returning recv/submit conventions instead. Use ZlinkException.fromErrno(...) only when implementing a custom native interop path that needs to construct a correctly-typed exception from a raw errno; that errno must be the one collected when the failing native call returned, not a value read by a later call. Ordinary application code never needs to call it, since every built-in API already throws the correctly-typed exception itself.

---

See contracts/errors/ and the Java binding spec for the full rationale.