kcp 0.1.0

data/ext/kcp/ikcp.h

@@ -0,0 +1,452 @@
+//=====================================================================
+//
+// KCP - A Better ARQ Protocol Implementation
+// skywind3000 (at) gmail.com, 2010-2011
+//  
+// Features:
+// + Average RTT reduce 30% - 40% vs traditional ARQ like tcp.
+// + Maximum RTT reduce three times vs tcp.
+// + Lightweight, distributed as a single source file.
+//
+//=====================================================================
+#ifndef _IKCP_H_
+#define _IKCP_H_
+
+#include <stddef.h>
+#include <stdlib.h>
+#include <assert.h>
+
+
+//=====================================================================
+// 32BIT INTEGER DEFINITION 
+//=====================================================================
+#ifndef __INTEGER_32_BITS__
+#define __INTEGER_32_BITS__
+#if defined(_WIN64) || defined(WIN64) || defined(__amd64__) || \
+	defined(__x86_64) || defined(__x86_64__) || defined(_M_IA64) || \
+	defined(_M_AMD64)
+	typedef unsigned int ISTDUINT32;
+	typedef int ISTDINT32;
+#elif defined(_WIN32) || defined(WIN32) || defined(__i386__) || \
+	defined(__i386) || defined(_M_X86)
+	typedef unsigned long ISTDUINT32;
+	typedef long ISTDINT32;
+#elif defined(__MACOS__)
+	typedef UInt32 ISTDUINT32;
+	typedef SInt32 ISTDINT32;
+#elif defined(__APPLE__) && defined(__MACH__)
+	#include <sys/types.h>
+	typedef u_int32_t ISTDUINT32;
+	typedef int32_t ISTDINT32;
+#elif defined(__BEOS__)
+	#include <sys/inttypes.h>
+	typedef u_int32_t ISTDUINT32;
+	typedef int32_t ISTDINT32;
+#elif (defined(_MSC_VER) || defined(__BORLANDC__)) && (!defined(__MSDOS__))
+	typedef unsigned __int32 ISTDUINT32;
+	typedef __int32 ISTDINT32;
+#elif defined(__GNUC__)
+	#include <stdint.h>
+	typedef uint32_t ISTDUINT32;
+	typedef int32_t ISTDINT32;
+#else 
+	typedef unsigned long ISTDUINT32; 
+	typedef long ISTDINT32;
+#endif
+#endif
+
+
+//=====================================================================
+// Integer Definition
+//=====================================================================
+#ifndef __IINT8_DEFINED
+#define __IINT8_DEFINED
+typedef char IINT8;
+#endif
+
+#ifndef __IUINT8_DEFINED
+#define __IUINT8_DEFINED
+typedef unsigned char IUINT8;
+#endif
+
+#ifndef __IUINT16_DEFINED
+#define __IUINT16_DEFINED
+typedef unsigned short IUINT16;
+#endif
+
+#ifndef __IINT16_DEFINED
+#define __IINT16_DEFINED
+typedef short IINT16;
+#endif
+
+#ifndef __IINT32_DEFINED
+#define __IINT32_DEFINED
+typedef ISTDINT32 IINT32;
+#endif
+
+#ifndef __IUINT32_DEFINED
+#define __IUINT32_DEFINED
+typedef ISTDUINT32 IUINT32;
+#endif
+
+#ifndef __IINT64_DEFINED
+#define __IINT64_DEFINED
+#if defined(_MSC_VER) || defined(__BORLANDC__)
+typedef __int64 IINT64;
+#else
+typedef long long IINT64;
+#endif
+#endif
+
+#ifndef __IUINT64_DEFINED
+#define __IUINT64_DEFINED
+#if defined(_MSC_VER) || defined(__BORLANDC__)
+typedef unsigned __int64 IUINT64;
+#else
+typedef unsigned long long IUINT64;
+#endif
+#endif
+
+#ifndef INLINE
+#if defined(__GNUC__)
+
+#if (__GNUC__ > 3) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1))
+#define INLINE         __inline__ __attribute__((always_inline))
+#else
+#define INLINE         __inline__
+#endif
+
+#elif (defined(_MSC_VER) || defined(__BORLANDC__) || defined(__WATCOMC__))
+#define INLINE __inline
+#else
+#define INLINE 
+#endif
+#endif
+
+#if (!defined(__cplusplus)) && (!defined(inline))
+#define inline INLINE
+#endif
+
+
+//=====================================================================
+// QUEUE DEFINITION                                                  
+//=====================================================================
+#ifndef __IQUEUE_DEF__
+#define __IQUEUE_DEF__
+
+struct IQUEUEHEAD {
+	struct IQUEUEHEAD *next, *prev;
+};
+
+typedef struct IQUEUEHEAD iqueue_head;
+
+
+//---------------------------------------------------------------------
+// queue init                                                         
+//---------------------------------------------------------------------
+#define IQUEUE_HEAD_INIT(name) { &(name), &(name) }
+#define IQUEUE_HEAD(name) \
+	struct IQUEUEHEAD name = IQUEUE_HEAD_INIT(name)
+
+#define IQUEUE_INIT(ptr) ( \
+	(ptr)->next = (ptr), (ptr)->prev = (ptr))
+
+#define IOFFSETOF(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)
+
+#define ICONTAINEROF(ptr, type, member) ( \
+		(type*)( ((char*)((type*)ptr)) - IOFFSETOF(type, member)) )
+
+#define IQUEUE_ENTRY(ptr, type, member) ICONTAINEROF(ptr, type, member)
+
+
+//---------------------------------------------------------------------
+// queue operation                     
+//---------------------------------------------------------------------
+#define IQUEUE_ADD(node, head) ( \
+	(node)->prev = (head), (node)->next = (head)->next, \
+	(head)->next->prev = (node), (head)->next = (node))
+
+#define IQUEUE_ADD_TAIL(node, head) ( \
+	(node)->prev = (head)->prev, (node)->next = (head), \
+	(head)->prev->next = (node), (head)->prev = (node))
+
+#define IQUEUE_DEL_BETWEEN(p, n) ((n)->prev = (p), (p)->next = (n))
+
+#define IQUEUE_DEL(entry) (\
+	(entry)->next->prev = (entry)->prev, \
+	(entry)->prev->next = (entry)->next, \
+	(entry)->next = 0, (entry)->prev = 0)
+
+#define IQUEUE_DEL_INIT(entry) do { \
+	IQUEUE_DEL(entry); IQUEUE_INIT(entry); } while (0)
+
+#define IQUEUE_IS_EMPTY(entry) ((entry) == (entry)->next)
+
+#define iqueue_init		IQUEUE_INIT
+#define iqueue_entry	IQUEUE_ENTRY
+#define iqueue_add		IQUEUE_ADD
+#define iqueue_add_tail	IQUEUE_ADD_TAIL
+#define iqueue_del		IQUEUE_DEL
+#define iqueue_del_init	IQUEUE_DEL_INIT
+#define iqueue_is_empty IQUEUE_IS_EMPTY
+
+#define IQUEUE_FOREACH(iterator, head, TYPE, MEMBER) \
+	for ((iterator) = iqueue_entry((head)->next, TYPE, MEMBER); \
+		&((iterator)->MEMBER) != (head); \
+		(iterator) = iqueue_entry((iterator)->MEMBER.next, TYPE, MEMBER))
+
+#define iqueue_foreach(iterator, head, TYPE, MEMBER) \
+	IQUEUE_FOREACH(iterator, head, TYPE, MEMBER)
+
+#define iqueue_foreach_entry(pos, head) \
+	for( (pos) = (head)->next; (pos) != (head) ; (pos) = (pos)->next )
+	
+
+#define __iqueue_splice(list, head) do {	\
+		iqueue_head *first = (list)->next, *last = (list)->prev; \
+		iqueue_head *at = (head)->next; \
+		(first)->prev = (head), (head)->next = (first);		\
+		(last)->next = (at), (at)->prev = (last); }	while (0)
+
+#define iqueue_splice(list, head) do { \
+	if (!iqueue_is_empty(list)) __iqueue_splice(list, head); } while (0)
+
+#define iqueue_splice_init(list, head) do {	\
+	iqueue_splice(list, head);	iqueue_init(list); } while (0)
+
+
+#ifdef _MSC_VER
+#pragma warning(disable:4311)
+#pragma warning(disable:4312)
+#pragma warning(disable:4996)
+#endif
+
+#endif
+
+
+//---------------------------------------------------------------------
+// BYTE ORDER & ALIGNMENT
+//---------------------------------------------------------------------
+#ifndef IWORDS_BIG_ENDIAN
+    #ifdef _BIG_ENDIAN_
+        #if _BIG_ENDIAN_
+            #define IWORDS_BIG_ENDIAN 1
+        #endif
+    #endif
+    #ifndef IWORDS_BIG_ENDIAN
+        #if defined(__hppa__) || \
+            defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \
+            (defined(__MIPS__) && defined(__MIPSEB__)) || \
+            defined(__ppc__) || defined(__POWERPC__) || defined(_M_PPC) || \
+            defined(__sparc__) || defined(__powerpc__) || \
+            defined(__mc68000__) || defined(__s390x__) || defined(__s390__)
+            #define IWORDS_BIG_ENDIAN 1
+        #endif
+    #endif
+    #ifndef IWORDS_BIG_ENDIAN
+        #define IWORDS_BIG_ENDIAN  0
+    #endif
+#endif
+
+#ifndef IWORDS_MUST_ALIGN
+	#if defined(__i386__) || defined(__i386) || defined(_i386_)
+		#define IWORDS_MUST_ALIGN 0
+	#elif defined(_M_IX86) || defined(_X86_) || defined(__x86_64__)
+		#define IWORDS_MUST_ALIGN 0
+	#elif defined(__amd64) || defined(__amd64__)
+		#define IWORDS_MUST_ALIGN 0
+	#else
+		#define IWORDS_MUST_ALIGN 1
+	#endif
+#endif
+
+
+//=====================================================================
+// Predefine struct
+//=====================================================================
+struct IKCPCB;
+typedef struct IKCPCB ikcpcb;
+
+
+//=====================================================================
+// SEGMENT
+//=====================================================================
+struct IKCPSEG
+{
+	struct IQUEUEHEAD node;
+	IUINT32 conv;
+	IUINT32 cmd;
+	IUINT32 frg;
+	IUINT32 wnd;
+	IUINT32 ts;
+	IUINT32 sn;
+	IUINT32 una;
+	IUINT32 len;
+	IUINT32 resendts;
+	IUINT32 rto;
+	IUINT32 fastack;
+	IUINT32 xmit;
+	char data[1];
+};
+
+
+//---------------------------------------------------------------------
+// IKCPOPS - pluggable congestion control operations
+//---------------------------------------------------------------------
+struct IKCPOPS
+{
+	const char *name;
+	int (*init)(ikcpcb *kcp);
+	void (*release)(ikcpcb *kcp);
+	void (*on_ack)(ikcpcb *kcp, IUINT32 acked_segs, IUINT32 acked_bytes,
+			IUINT32 prior_in_flight);
+	void (*on_fast_retransmit)(ikcpcb *kcp, IUINT32 fast_retrans,
+				IUINT32 inflight, IUINT32 prior_cwnd);
+	void (*on_timeout)(ikcpcb *kcp, IUINT32 prior_cwnd);
+	void (*on_tick)(ikcpcb *kcp);
+	void (*on_app_limited)(ikcpcb *kcp, IUINT32 inflight);
+	void (*on_rtt)(ikcpcb *kcp, IINT32 rtt);
+	void (*on_pkt_sent)(ikcpcb *kcp, IUINT32 sn, IUINT32 ts,
+				IUINT32 len, IUINT32 inflight, IUINT32 xmit);
+	void (*on_pkt_acked)(ikcpcb *kcp, IUINT32 sn, IUINT32 ts,
+				IUINT32 len, IINT32 rtt, IUINT32 xmit);
+	IUINT32 (*get_info)(ikcpcb *kcp, void *buf, IUINT32 bufsize);
+	IUINT32 (*pacing_rate)(ikcpcb *kcp);
+};
+
+
+//---------------------------------------------------------------------
+// IKCPCB
+//---------------------------------------------------------------------
+struct IKCPCB
+{
+	IUINT32 conv, mtu, mss, state;
+	IUINT32 snd_una, snd_nxt, rcv_nxt;
+	IUINT32 ts_recent, ts_lastack, ssthresh;
+	IINT32 rx_rttval, rx_srtt, rx_rto, rx_minrto;
+	IUINT32 snd_wnd, rcv_wnd, rmt_wnd, cwnd, probe;
+	IUINT32 current, interval, ts_flush, xmit;
+	IUINT32 nrcv_buf, nsnd_buf;
+	IUINT32 nrcv_que, nsnd_que;
+	IUINT32 nodelay, updated;
+	IUINT32 ts_probe, probe_wait;
+	IUINT32 dead_link, incr;
+	struct IQUEUEHEAD snd_queue;
+	struct IQUEUEHEAD rcv_queue;
+	struct IQUEUEHEAD snd_buf;
+	struct IQUEUEHEAD rcv_buf;
+	IUINT32 *acklist;
+	IUINT32 ackcount;
+	IUINT32 ackblock;
+	IUINT32 ackedlen;
+	void *user;
+	char *buffer;
+	int fastresend;
+	int fastlimit;
+	int nocwnd, stream;
+	const struct IKCPOPS *ccops;
+	void *congest;
+	int logmask;
+	int (*output)(const char *buf, int len, struct IKCPCB *kcp, void *user);
+	void (*writelog)(const char *log, struct IKCPCB *kcp, void *user);
+};
+
+
+#define IKCP_LOG_OUTPUT			1
+#define IKCP_LOG_INPUT			2
+#define IKCP_LOG_SEND			4
+#define IKCP_LOG_RECV			8
+#define IKCP_LOG_IN_DATA		16
+#define IKCP_LOG_IN_ACK			32
+#define IKCP_LOG_IN_PROBE		64
+#define IKCP_LOG_IN_WINS		128
+#define IKCP_LOG_OUT_DATA		256
+#define IKCP_LOG_OUT_ACK		512
+#define IKCP_LOG_OUT_PROBE		1024
+#define IKCP_LOG_OUT_WINS		2048
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+//---------------------------------------------------------------------
+// interface
+//---------------------------------------------------------------------
+
+// create a new kcp control object, 'conv' must be equal in both endpoints
+// of the same connection. 'user' will be passed to the output callback.
+// output callback can be set up like this: 'kcp->output = my_udp_output'
+ikcpcb* ikcp_create(IUINT32 conv, void *user);
+
+// release kcp control object
+void ikcp_release(ikcpcb *kcp);
+
+// set output callback, which will be invoked by kcp
+void ikcp_setoutput(ikcpcb *kcp, int (*output)(const char *buf, int len, 
+	ikcpcb *kcp, void *user));
+
+// user/upper level recv: returns size, returns below zero for EAGAIN
+int ikcp_recv(ikcpcb *kcp, char *buffer, int len);
+
+// user/upper level send, returns below zero for error
+int ikcp_send(ikcpcb *kcp, const char *buffer, int len);
+
+// update state (call it repeatedly, every 10ms-100ms), or you can ask 
+// ikcp_check when to call it again (without ikcp_input/_send calling).
+// 'current' - current timestamp in millisec. 
+void ikcp_update(ikcpcb *kcp, IUINT32 current);
+
+// Determines when you should invoke ikcp_update next:
+// returns the timestamp (in milliseconds) at which you should call
+// ikcp_update, assuming no ikcp_input/_send calls occur in between.
+// You can call ikcp_update at that time instead of calling it repeatedly.
+// Important for reducing unnecessary ikcp_update invocations. Use it to
+// schedule ikcp_update (e.g., implementing an epoll-like mechanism,
+// or optimizing ikcp_update when handling massive kcp connections).
+IUINT32 ikcp_check(const ikcpcb *kcp, IUINT32 current);
+
+// when you receive a low-level packet (e.g., UDP packet), call this
+int ikcp_input(ikcpcb *kcp, const char *data, long size);
+
+// flush pending data
+void ikcp_flush(ikcpcb *kcp);
+
+// check the size of next message in the recv queue
+int ikcp_peeksize(const ikcpcb *kcp);
+
+// change MTU size, default is 1400
+int ikcp_setmtu(ikcpcb *kcp, int mtu);
+
+// set maximum window size: sndwnd=32, rcvwnd=32 by default
+int ikcp_wndsize(ikcpcb *kcp, int sndwnd, int rcvwnd);
+
+// get how many packets are waiting to be sent
+int ikcp_waitsnd(const ikcpcb *kcp);
+
+// fastest: ikcp_nodelay(kcp, 1, 20, 2, 1)
+// nodelay: 0:disable (default), 1:enable
+// interval: internal update timer interval in ms, default is 100ms
+// resend: 0:disable fast resend (default), 1:enable fast resend
+// nc: 0:normal congestion control (default), 1:disable congestion control
+int ikcp_nodelay(ikcpcb *kcp, int nodelay, int interval, int resend, int nc);
+
+// install congestion control algorithm, NULL restores builtin
+int ikcp_setcc(ikcpcb *kcp, const struct IKCPOPS *ops);
+
+// write log with kcp->writelog
+void ikcp_log(ikcpcb *kcp, int mask, const char *fmt, ...);
+
+// setup allocator
+void ikcp_allocator(void* (*new_malloc)(size_t), void (*new_free)(void*));
+
+// read conv
+IUINT32 ikcp_getconv(const void *ptr);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+
+

data/ext/kcp/kcp_native.c

@@ -0,0 +1,137 @@
+// kcp_native.c — native Ruby extension wrapping KCP (ikcp.c) with a pull-model
+// API so Ruby never needs C->Ruby callbacks. The kcp context is wrapped with
+// TypedData_Wrap_Struct, which is safe on 32/64-bit and Windows (no pointer
+// truncation).
+
+#include "ruby.h"
+#include "ikcp.h"
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+    ikcpcb *kcp;
+    char *out;
+    int outlen;
+    int outcap;
+} kcp_ctx;
+
+/* Max bytes returned per output() call -- safely under the 64KB UDP datagram
+   limit, so a burst of KCP packets never overflows a single sendto(). */
+#define KCP_MAX_BLOB 60000
+
+static int shim_output(const char *buf, int len, ikcpcb *kcp, void *user) {
+    kcp_ctx *ctx = (kcp_ctx *)user;
+    if (ctx->outlen + len > ctx->outcap) {
+        ctx->outcap = (ctx->outlen + len) * 2 + 256;
+        ctx->out = (char *)realloc(ctx->out, ctx->outcap);
+    }
+    memcpy(ctx->out + ctx->outlen, buf, len);
+    ctx->outlen += len;
+    return 0;
+}
+
+static void ctx_free(void *ptr) {
+    kcp_ctx *ctx = (kcp_ctx *)ptr;
+    if (ctx) {
+        if (ctx->kcp) ikcp_release(ctx->kcp);
+        free(ctx->out);
+        free(ctx);
+    }
+}
+
+static const rb_data_type_t kcp_ctx_type = {
+    "mnet/kcp_ctx",
+    {0, ctx_free, 0,},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static kcp_ctx *get_ctx(VALUE self) {
+    kcp_ctx *ctx;
+    TypedData_Get_Struct(self, kcp_ctx, &kcp_ctx_type, ctx);
+    return ctx;
+}
+
+static VALUE m_kcp_new(VALUE mod, VALUE conv) {
+    kcp_ctx *ctx = (kcp_ctx *)calloc(1, sizeof(kcp_ctx));
+    ctx->kcp = ikcp_create(NUM2UINT(conv), ctx);
+    ikcp_setoutput(ctx->kcp, shim_output);
+    ikcp_nodelay(ctx->kcp, 1, 10, 2, 1);
+    ikcp_wndsize(ctx->kcp, 128, 128);
+    ctx->kcp->stream = 1; /* byte-stream mode */
+    return TypedData_Wrap_Struct(rb_cObject, &kcp_ctx_type, ctx);
+}
+
+static VALUE m_kcp_send(VALUE mod, VALUE self, VALUE data) {
+    kcp_ctx *ctx = get_ctx(self);
+    StringValue(data);
+    return INT2NUM(ikcp_send(ctx->kcp, RSTRING_PTR(data), (int)RSTRING_LEN(data)));
+}
+
+static VALUE m_kcp_recv(VALUE mod, VALUE self, VALUE maxlen) {
+    kcp_ctx *ctx = get_ctx(self);
+    int n = NUM2INT(maxlen);
+    char *tmp = (char *)malloc((size_t)n);
+    if (!tmp) rb_raise(rb_eNoMemError, "kcp recv buffer");
+    int got = ikcp_recv(ctx->kcp, tmp, n);
+    if (got <= 0) {
+        free(tmp);
+        return Qnil;
+    }
+    VALUE buf = rb_str_new(tmp, got);
+    free(tmp);
+    return buf;
+}
+
+static VALUE m_kcp_input(VALUE mod, VALUE self, VALUE data) {
+    kcp_ctx *ctx = get_ctx(self);
+    StringValue(data);
+    return INT2NUM(ikcp_input(ctx->kcp, RSTRING_PTR(data), (long)RSTRING_LEN(data)));
+}
+
+static VALUE m_kcp_update(VALUE mod, VALUE self, VALUE now) {
+    kcp_ctx *ctx = get_ctx(self);
+    ikcp_update(ctx->kcp, NUM2UINT(now));
+    return Qnil;
+}
+
+static VALUE m_kcp_flush(VALUE mod, VALUE self) {
+    kcp_ctx *ctx = get_ctx(self);
+    /* ikcp_flush returns early if ikcp_update hasn't run yet; initialize the
+       flag so a bare send+flush works without a prior update call. */
+    if (ctx->kcp->updated == 0) {
+        ctx->kcp->updated = 1;
+        ctx->kcp->ts_flush = ctx->kcp->current;
+    }
+    ikcp_flush(ctx->kcp);
+    return Qnil;
+}
+
+static VALUE m_kcp_output(VALUE mod, VALUE self) {
+    kcp_ctx *ctx = get_ctx(self);
+    if (ctx->outlen <= 0) return Qnil;
+    /* 一次最多返回 60KB 拼接好的包，避免单个 UDP 数据报超过 64KB（EMSGSIZE） */
+    int n = ctx->outlen < KCP_MAX_BLOB ? ctx->outlen : KCP_MAX_BLOB;
+    VALUE buf = rb_str_new(ctx->out, n);
+    if (n < ctx->outlen) {
+        memmove(ctx->out, ctx->out + n, ctx->outlen - n);
+    }
+    ctx->outlen -= n;
+    return buf;
+}
+
+static VALUE m_kcp_waitsnd(VALUE mod, VALUE self) {
+    kcp_ctx *ctx = get_ctx(self);
+    return INT2NUM(ikcp_waitsnd(ctx->kcp));
+}
+
+void Init_kcp_native(void) {
+    VALUE m = rb_define_module("KcpNative");
+    rb_define_singleton_method(m, "kcp_new", m_kcp_new, 1);
+    rb_define_singleton_method(m, "kcp_send", m_kcp_send, 2);
+    rb_define_singleton_method(m, "kcp_recv", m_kcp_recv, 2);
+    rb_define_singleton_method(m, "kcp_input", m_kcp_input, 2);
+    rb_define_singleton_method(m, "kcp_update", m_kcp_update, 2);
+    rb_define_singleton_method(m, "kcp_flush", m_kcp_flush, 1);
+    rb_define_singleton_method(m, "kcp_output", m_kcp_output, 1);
+    rb_define_singleton_method(m, "kcp_waitsnd", m_kcp_waitsnd, 1);
+}

data/lib/kcp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kcp
+  VERSION = '0.1.0'
+end

data/lib/kcp.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# KCP 是一个快速、可靠的 ARQ 协议（C 实现，来自 skywind3000/kcp）。
+# 本 gem 通过原生扩展把 KCP 封装成「拉取式」接口，供上层传输协议使用。
+
+require 'kcp/version'
+require 'kcp_native'
+
+module Kcp
+  # 可靠字节流引擎（stream 模式）。它只负责「把一段字节流可靠送达对端」，
+  # 不处理网络 I/O、地址、加密 —— 这些由调用方负责。
+  #
+  # 用法：
+  #   engine = Kcp::Engine.new(conv)
+  #   engine.send(data)            # 把数据排队
+  #   engine.flush                 # 立即刷出（生成 KCP 包）
+  #   pkt = engine.output          # 取出待发送的编码包，交给 UDP sendto
+  #   engine.input(recv_pkt)       # 喂入收到的编码包
+  #   chunk = engine.recv          # 取出对端送来的可靠字节流
+  #   engine.update(now_ms)        # 周期性驱动（重传/窗口更新）
+  class Engine
+    # conv 是会话标识（uint32），连接两端必须一致。
+    def initialize(conv)
+      @ctx = KcpNative.kcp_new(conv)
+    end
+
+    # 把数据排队等待可靠发送。返回排入的字节数，出错返回负数。
+    # 注意：数据不会立即发出去，需要调用 #flush（或 #update）刷出。
+    def send(data)
+      KcpNative.kcp_send(@ctx, data)
+    end
+
+    # 取出对端已送达的、按序的字节流（最多 maxlen 字节）。
+    # 没有数据时返回 nil。
+    def recv(maxlen = 65_536)
+      KcpNative.kcp_recv(@ctx, maxlen)
+    end
+
+    # 喂入一个收到的 KCP 编码包（低层 UDP 数据报的内容）。
+    def input(data)
+      KcpNative.kcp_input(@ctx, data)
+    end
+
+    # 驱动 KCP 时钟（按间隔触发的重传、ACK、窗口探测）。now_ms 是毫秒时间戳，
+    # 内部会截断到 32 位（KCP 用 uint32 毫秒，约 49 天回绕一次，属正常）。
+    def update(now_ms)
+      KcpNative.kcp_update(@ctx, now_ms.to_i & 0xffffffff)
+    end
+
+    # 立即刷出待发送数据（不受 update 的间隔节流）。
+    def flush
+      KcpNative.kcp_flush(@ctx)
+    end
+
+    # 取出待发送的编码包（一次一个 KCP 包），交给低层发送。没有待发送时返回 nil。
+    def output
+      KcpNative.kcp_output(@ctx)
+    end
+
+    # 发送队列里待发送的包数（>0 表示窗口已满、有积压）。
+    def waitsnd
+      KcpNative.kcp_waitsnd(@ctx)
+    end
+
+    # 释放引用（C 对象由 GC 回收）。
+    def close
+      @ctx = nil
+    end
+
+    private
+
+    def now_ms
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i & 0xffffffff
+    end
+  end
+end