feat: 基于Python ROS2的控制程序

2026-04-03 20:00:33 +08:00
parent 6ece408d9f
commit 9ffc36f50d
26 changed files with 2193 additions and 38 deletions
--- a/python/omnisocket/init.py
+++ b/python/omnisocket/init.py
@@ -6,6 +6,7 @@ try:
        MSG_TYPE_REGISTER,
        MSG_TYPE_TEXT,
        Session,
+        UdpSession,
    )
 except ImportError as exc:
    raise ImportError(
@@ -41,4 +42,5 @@ __all__ = [
    "MSG_TYPE_REGISTER",
    "MSG_TYPE_TEXT",
    "Session",
+    "UdpSession",
 ]
--- a/python/omnisocket/_omnisocket.c
+++ b/python/omnisocket/_omnisocket.c
@@ -8,6 +8,11 @@ typedef struct PyOmniSession {
    omnisocket_session_t session;
 } PyOmniSession;

+typedef struct PyOmniUdpSession {
+    PyObject_HEAD
+    omnisocket_udp_session_t session;
+} PyOmniUdpSession;
+
 PyDoc_STRVAR(
    PyOmniSession_recv_doc,
    "recv(timeout_ms=-1) -> (from_peer, msg_type, payload) | None"
@@ -22,6 +27,66 @@ PyDoc_STRVAR(
    "current frame has already been consumed and is lost."
 );

+static PyObject *build_recv_result(const message_t *msg) {
+    PyObject *body = NULL;
+    PyObject *result = NULL;
+
+    body = PyBytes_FromStringAndSize((const char *) msg->body, (Py_ssize_t) msg->body_len);
+    if (body == NULL) {
+        return NULL;
+    }
+    result = Py_BuildValue("(siO)", msg->from, (int) msg->type, body);
+    Py_DECREF(body);
+    return result;
+}
+
+static PyObject *build_recv_meta_dict(
+    const char *from_peer,
+    const char *to_peer,
+    const char *file_name,
+    int msg_type,
+    unsigned long long message_id,
+    unsigned long long body_len
+) {
+    return Py_BuildValue(
+        "{s:s,s:s,s:s,s:i,s:K,s:K}",
+        "from",
+        from_peer,
+        "to",
+        to_peer,
+        "file_name",
+        file_name,
+        "msg_type",
+        msg_type,
+        "message_id",
+        message_id,
+        "body_len",
+        body_len
+    );
+}
+
+static PyObject *build_stats_dict(const omnisocket_session_stats_t *stats) {
+    return Py_BuildValue(
+        "{s:K,s:K,s:K,s:K,s:K,s:K,s:K,s:i}",
+        "send_calls",
+        (unsigned long long) stats->send_calls,
+        "send_bytes",
+        (unsigned long long) stats->send_bytes,
+        "send_errors",
+        (unsigned long long) stats->send_errors,
+        "recv_calls",
+        (unsigned long long) stats->recv_calls,
+        "recv_bytes",
+        (unsigned long long) stats->recv_bytes,
+        "recv_timeouts",
+        (unsigned long long) stats->recv_timeouts,
+        "recv_errors",
+        (unsigned long long) stats->recv_errors,
+        "connected",
+        stats->connected
+    );
+}
+
 static PyObject *PyOmniSession_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) {
    PyOmniSession *self;
    (void) args;
@@ -165,7 +230,6 @@ static PyObject *PyOmniSession_recv(PyOmniSession *self, PyObject *args, PyObjec
    int timeout_ms = -1;
    int rc;
    message_t msg;
-    PyObject *body = NULL;
    PyObject *result = NULL;
    static char *kwlist[] = {"timeout_ms", NULL};

@@ -187,13 +251,7 @@ static PyObject *PyOmniSession_recv(PyOmniSession *self, PyObject *args, PyObjec
        return PyErr_SetFromErrno(PyExc_OSError);
    }

-    body = PyBytes_FromStringAndSize((const char *) msg.body, (Py_ssize_t) msg.body_len);
-    if (body == NULL) {
-        protocol_message_clear(&msg);
-        return NULL;
-    }
-    result = Py_BuildValue("(siO)", msg.from, (int) msg.type, body);
-    Py_DECREF(body);
+    result = build_recv_result(&msg);
    protocol_message_clear(&msg);
    return result;
 }
@@ -237,19 +295,12 @@ static PyObject *PyOmniSession_recv_into(PyOmniSession *self, PyObject *args, Py
        return PyErr_SetFromErrno(PyExc_OSError);
    }

-    result = Py_BuildValue(
-        "{s:s,s:s,s:s,s:i,s:K,s:K}",
-        "from",
+    result = build_recv_meta_dict(
        meta.from,
-        "to",
        meta.to,
-        "file_name",
        meta.file_name,
-        "msg_type",
        (int) meta.type,
-        "message_id",
        (unsigned long long) meta.id,
-        "body_len",
        (unsigned long long) meta.body_len
    );
    return result;
@@ -260,25 +311,7 @@ static PyObject *PyOmniSession_stats(PyOmniSession *self, PyObject *Py_UNUSED(ig

    memset(&stats, 0, sizeof(stats));
    omnisocket_session_stats_snapshot(&self->session, &stats);
-    return Py_BuildValue(
-        "{s:K,s:K,s:K,s:K,s:K,s:K,s:K,s:i}",
-        "send_calls",
-        (unsigned long long) stats.send_calls,
-        "send_bytes",
-        (unsigned long long) stats.send_bytes,
-        "send_errors",
-        (unsigned long long) stats.send_errors,
-        "recv_calls",
-        (unsigned long long) stats.recv_calls,
-        "recv_bytes",
-        (unsigned long long) stats.recv_bytes,
-        "recv_timeouts",
-        (unsigned long long) stats.recv_timeouts,
-        "recv_errors",
-        (unsigned long long) stats.recv_errors,
-        "connected",
-        stats.connected
-    );
+    return build_stats_dict(&stats);
 }

 static PyMethodDef PyOmniSession_methods[] = {
@@ -295,6 +328,211 @@ static PyTypeObject PyOmniSessionType = {
    PyVarObject_HEAD_INIT(NULL, 0)
 };

+static PyObject *PyOmniUdpSession_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) {
+    PyOmniUdpSession *self;
+    (void) args;
+    (void) kwargs;
+
+    self = (PyOmniUdpSession *) type->tp_alloc(type, 0);
+    if (self == NULL) {
+        return NULL;
+    }
+    if (omnisocket_udp_session_init(&self->session) != 0) {
+        type->tp_free((PyObject *) self);
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+    return (PyObject *) self;
+}
+
+static void PyOmniUdpSession_dealloc(PyOmniUdpSession *self) {
+    omnisocket_udp_session_destroy(&self->session);
+    Py_TYPE(self)->tp_free((PyObject *) self);
+}
+
+static PyObject *PyOmniUdpSession_connect(PyOmniUdpSession *self, PyObject *args, PyObject *kwargs) {
+    const char *server_addr;
+    const char *peer_id;
+    const char *bind_ip = "";
+    const char *bind_device = "";
+    int enable_timestamping = 0;
+    int rc;
+
+    static char *kwlist[] = {
+        "server_addr",
+        "peer_id",
+        "bind_ip",
+        "bind_device",
+        "enable_timestamping",
+        NULL
+    };
+
+    if (!PyArg_ParseTupleAndKeywords(
+            args,
+            kwargs,
+            "ss|ssi",
+            kwlist,
+            &server_addr,
+            &peer_id,
+            &bind_ip,
+            &bind_device,
+            &enable_timestamping)) {
+        return NULL;
+    }
+
+    Py_BEGIN_ALLOW_THREADS
+    rc = omnisocket_udp_session_connect(
+        &self->session,
+        server_addr,
+        peer_id,
+        bind_ip,
+        bind_device,
+        enable_timestamping
+    );
+    Py_END_ALLOW_THREADS
+
+    if (rc != 0) {
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+    Py_RETURN_NONE;
+}
+
+static PyObject *PyOmniUdpSession_close(PyOmniUdpSession *self, PyObject *Py_UNUSED(ignored)) {
+    int rc;
+
+    Py_BEGIN_ALLOW_THREADS
+    rc = omnisocket_udp_session_close(&self->session);
+    Py_END_ALLOW_THREADS
+
+    if (rc != 0) {
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+    Py_RETURN_NONE;
+}
+
+static PyObject *PyOmniUdpSession_send(PyOmniUdpSession *self, PyObject *args, PyObject *kwargs) {
+    const char *to;
+    Py_buffer payload;
+    int rc;
+    static char *kwlist[] = {"to", "data", NULL};
+
+    memset(&payload, 0, sizeof(payload));
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "sy*", kwlist, &to, &payload)) {
+        return NULL;
+    }
+
+    Py_BEGIN_ALLOW_THREADS
+    rc = omnisocket_udp_session_send(&self->session, to, payload.buf, (size_t) payload.len);
+    Py_END_ALLOW_THREADS
+
+    PyBuffer_Release(&payload);
+    if (rc != 0) {
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+    Py_RETURN_NONE;
+}
+
+static PyObject *PyOmniUdpSession_recv(PyOmniUdpSession *self, PyObject *args, PyObject *kwargs) {
+    int timeout_ms = -1;
+    int rc;
+    message_t msg;
+    PyObject *result = NULL;
+    static char *kwlist[] = {"timeout_ms", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|i", kwlist, &timeout_ms)) {
+        return NULL;
+    }
+
+    protocol_message_init(&msg);
+    Py_BEGIN_ALLOW_THREADS
+    rc = omnisocket_udp_session_recv(&self->session, &msg, timeout_ms);
+    Py_END_ALLOW_THREADS
+
+    if (rc == 1) {
+        protocol_message_clear(&msg);
+        Py_RETURN_NONE;
+    }
+    if (rc != 0) {
+        protocol_message_clear(&msg);
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+
+    result = build_recv_result(&msg);
+    protocol_message_clear(&msg);
+    return result;
+}
+
+static PyObject *PyOmniUdpSession_recv_into(PyOmniUdpSession *self, PyObject *args, PyObject *kwargs) {
+    PyObject *buffer_obj;
+    Py_buffer view;
+    int timeout_ms = -1;
+    int rc;
+    udp_client_recv_meta_t meta;
+    PyObject *result = NULL;
+    static char *kwlist[] = {"buffer", "timeout_ms", NULL};
+
+    memset(&view, 0, sizeof(view));
+    memset(&meta, 0, sizeof(meta));
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O|i", kwlist, &buffer_obj, &timeout_ms)) {
+        return NULL;
+    }
+    if (PyObject_GetBuffer(buffer_obj, &view, PyBUF_WRITABLE) != 0) {
+        return NULL;
+    }
+
+    Py_BEGIN_ALLOW_THREADS
+    rc = omnisocket_udp_session_recv_into(&self->session, view.buf, (size_t) view.len, &meta, timeout_ms);
+    Py_END_ALLOW_THREADS
+
+    PyBuffer_Release(&view);
+    if (rc == 1) {
+        Py_RETURN_NONE;
+    }
+    if (rc == 2) {
+        PyErr_Format(
+            PyExc_BufferError,
+            "buffer too small: need %zu bytes; current frame was already consumed and dropped",
+            meta.body_len
+        );
+        return NULL;
+    }
+    if (rc != 0) {
+        return PyErr_SetFromErrno(PyExc_OSError);
+    }
+
+    result = build_recv_meta_dict(
+        meta.from,
+        meta.to,
+        meta.file_name,
+        (int) meta.type,
+        (unsigned long long) meta.id,
+        (unsigned long long) meta.body_len
+    );
+    return result;
+}
+
+static PyObject *PyOmniUdpSession_stats(PyOmniUdpSession *self, PyObject *Py_UNUSED(ignored)) {
+    omnisocket_session_stats_t stats;
+
+    memset(&stats, 0, sizeof(stats));
+    omnisocket_udp_session_stats_snapshot(&self->session, &stats);
+    return build_stats_dict(&stats);
+}
+
+static PyMethodDef PyOmniUdpSession_methods[] = {
+    {"connect", (PyCFunction) PyOmniUdpSession_connect, METH_VARARGS | METH_KEYWORDS, NULL},
+    {"close", (PyCFunction) PyOmniUdpSession_close, METH_NOARGS, NULL},
+    {"send", (PyCFunction) PyOmniUdpSession_send, METH_VARARGS | METH_KEYWORDS, NULL},
+    {"recv", (PyCFunction) PyOmniUdpSession_recv, METH_VARARGS | METH_KEYWORDS, PyOmniSession_recv_doc},
+    {"recv_into", (PyCFunction) PyOmniUdpSession_recv_into, METH_VARARGS | METH_KEYWORDS, PyOmniSession_recv_into_doc},
+    {"stats", (PyCFunction) PyOmniUdpSession_stats, METH_NOARGS, NULL},
+    {NULL, NULL, 0, NULL}
+};
+
+static PyTypeObject PyOmniUdpSessionType = {
+    PyVarObject_HEAD_INIT(NULL, 0)
+};
+
 static PyModuleDef omnisocket_module = {
    PyModuleDef_HEAD_INIT,
    .m_name = "_omnisocket",
@@ -315,6 +553,17 @@ PyMODINIT_FUNC PyInit__omnisocket(void) {
        return NULL;
    }

+    PyOmniUdpSessionType.tp_name = "omnisocket.UdpSession";
+    PyOmniUdpSessionType.tp_basicsize = sizeof(PyOmniUdpSession);
+    PyOmniUdpSessionType.tp_flags = Py_TPFLAGS_DEFAULT;
+    PyOmniUdpSessionType.tp_new = PyOmniUdpSession_new;
+    PyOmniUdpSessionType.tp_dealloc = (destructor) PyOmniUdpSession_dealloc;
+    PyOmniUdpSessionType.tp_methods = PyOmniUdpSession_methods;
+
+    if (PyType_Ready(&PyOmniUdpSessionType) < 0) {
+        return NULL;
+    }
+
    module = PyModule_Create(&omnisocket_module);
    if (module == NULL) {
        return NULL;
@@ -327,6 +576,13 @@ PyMODINIT_FUNC PyInit__omnisocket(void) {
        return NULL;
    }

+    Py_INCREF(&PyOmniUdpSessionType);
+    if (PyModule_AddObject(module, "UdpSession", (PyObject *) &PyOmniUdpSessionType) != 0) {
+        Py_DECREF(&PyOmniUdpSessionType);
+        Py_DECREF(module);
+        return NULL;
+    }
+
    if (PyModule_AddIntConstant(module, "MSG_TYPE_TEXT", MSG_TYPE_TEXT) != 0 ||
        PyModule_AddIntConstant(module, "MSG_TYPE_FILE", MSG_TYPE_FILE) != 0 ||
        PyModule_AddIntConstant(module, "MSG_TYPE_REGISTER", MSG_TYPE_REGISTER) != 0 ||
--- a/python/omnisocket/omnisocket_client.c
+++ b/python/omnisocket/omnisocket_client.c
@@ -246,3 +246,245 @@ void omnisocket_session_stats_snapshot(omnisocket_session_t *session, omnisocket
    *out_stats = session->stats;
    pthread_mutex_unlock(&session->mutex);
 }
+
+int omnisocket_udp_session_init(omnisocket_udp_session_t *session) {
+    int rc;
+
+    if (session == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+    memset(session, 0, sizeof(*session));
+    rc = pthread_mutex_init(&session->mutex, NULL);
+    if (rc != 0) {
+        errno = rc;
+        return -1;
+    }
+    rc = pthread_cond_init(&session->idle_cond, NULL);
+    if (rc != 0) {
+        pthread_mutex_destroy(&session->mutex);
+        errno = rc;
+        return -1;
+    }
+    return 0;
+}
+
+void omnisocket_udp_session_destroy(omnisocket_udp_session_t *session) {
+    if (session == NULL) {
+        return;
+    }
+    (void) omnisocket_udp_session_close(session);
+    pthread_cond_destroy(&session->idle_cond);
+    pthread_mutex_destroy(&session->mutex);
+}
+
+static int omnisocket_udp_session_begin_client_op(omnisocket_udp_session_t *session, udp_client_t **out_client) {
+    if (session == NULL || out_client == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    pthread_mutex_lock(&session->mutex);
+    if (session->closing) {
+        pthread_mutex_unlock(&session->mutex);
+        errno = ECANCELED;
+        return -1;
+    }
+    if (session->client == NULL) {
+        pthread_mutex_unlock(&session->mutex);
+        errno = ENOTCONN;
+        return -1;
+    }
+    *out_client = session->client;
+    session->active_ops += 1;
+    pthread_mutex_unlock(&session->mutex);
+    return 0;
+}
+
+int omnisocket_udp_session_connect(
+    omnisocket_udp_session_t *session,
+    const char *server_addr,
+    const char *peer_id,
+    const char *bind_ip,
+    const char *bind_device,
+    int enable_timestamping
+) {
+    udp_client_t *client;
+
+    if (session == NULL || server_addr == NULL || peer_id == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    pthread_mutex_lock(&session->mutex);
+    while (session->closing) {
+        pthread_cond_wait(&session->idle_cond, &session->mutex);
+    }
+    if (session->client != NULL) {
+        pthread_mutex_unlock(&session->mutex);
+        errno = EISCONN;
+        return -1;
+    }
+    client = udp_client_dial_with_options(
+        server_addr,
+        peer_id,
+        bind_ip,
+        bind_device,
+        NULL,
+        NULL,
+        enable_timestamping
+    );
+    if (client == NULL) {
+        pthread_mutex_unlock(&session->mutex);
+        return -1;
+    }
+    session->client = client;
+    session->stats.connected = 1;
+    pthread_mutex_unlock(&session->mutex);
+    return 0;
+}
+
+int omnisocket_udp_session_close(omnisocket_udp_session_t *session) {
+    udp_client_t *client;
+
+    if (session == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    pthread_mutex_lock(&session->mutex);
+    while (session->closing) {
+        pthread_cond_wait(&session->idle_cond, &session->mutex);
+    }
+    client = session->client;
+    if (client != NULL) {
+        session->closing = 1;
+        session->client = NULL;
+    }
+    session->stats.connected = 0;
+    pthread_mutex_unlock(&session->mutex);
+
+    if (client != NULL) {
+        udp_client_close(client);
+        pthread_mutex_lock(&session->mutex);
+        while (session->active_ops > 0) {
+            pthread_cond_wait(&session->idle_cond, &session->mutex);
+        }
+        pthread_mutex_unlock(&session->mutex);
+        udp_client_free(client);
+        pthread_mutex_lock(&session->mutex);
+        session->closing = 0;
+        pthread_cond_broadcast(&session->idle_cond);
+        pthread_mutex_unlock(&session->mutex);
+    }
+    return 0;
+}
+
+int omnisocket_udp_session_send(omnisocket_udp_session_t *session, const char *to, const void *data, size_t data_len) {
+    udp_client_t *client;
+    int rc;
+
+    if (session == NULL || to == NULL || (data == NULL && data_len > 0)) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if (omnisocket_udp_session_begin_client_op(session, &client) != 0) {
+        return -1;
+    }
+    rc = udp_client_send_binary(client, to, data, data_len);
+    pthread_mutex_lock(&session->mutex);
+    if (rc == 0) {
+        session->stats.send_calls += 1;
+        session->stats.send_bytes += (uint64_t) data_len;
+    } else {
+        session->stats.send_errors += 1;
+    }
+    if (session->active_ops > 0) {
+        session->active_ops -= 1;
+    }
+    if (session->closing && session->active_ops == 0) {
+        pthread_cond_broadcast(&session->idle_cond);
+    }
+    pthread_mutex_unlock(&session->mutex);
+    return rc;
+}
+
+int omnisocket_udp_session_recv(omnisocket_udp_session_t *session, message_t *out_msg, int timeout_ms) {
+    udp_client_t *client;
+    int rc;
+
+    if (session == NULL || out_msg == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if (omnisocket_udp_session_begin_client_op(session, &client) != 0) {
+        return -1;
+    }
+    rc = udp_client_receive_timed(client, out_msg, timeout_ms);
+    pthread_mutex_lock(&session->mutex);
+    if (rc == 0) {
+        session->stats.recv_calls += 1;
+        session->stats.recv_bytes += (uint64_t) out_msg->body_len;
+    } else if (rc == 1) {
+        session->stats.recv_timeouts += 1;
+    } else {
+        session->stats.recv_errors += 1;
+    }
+    if (session->active_ops > 0) {
+        session->active_ops -= 1;
+    }
+    if (session->closing && session->active_ops == 0) {
+        pthread_cond_broadcast(&session->idle_cond);
+    }
+    pthread_mutex_unlock(&session->mutex);
+    return rc;
+}
+
+int omnisocket_udp_session_recv_into(
+    omnisocket_udp_session_t *session,
+    void *buffer,
+    size_t buffer_len,
+    udp_client_recv_meta_t *out_meta,
+    int timeout_ms
+) {
+    udp_client_t *client;
+    int rc;
+
+    if (session == NULL || out_meta == NULL || (buffer == NULL && buffer_len > 0)) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if (omnisocket_udp_session_begin_client_op(session, &client) != 0) {
+        return -1;
+    }
+    rc = udp_client_receive_into(client, buffer, buffer_len, out_meta, timeout_ms);
+    pthread_mutex_lock(&session->mutex);
+    if (rc == 0) {
+        session->stats.recv_calls += 1;
+        session->stats.recv_bytes += (uint64_t) out_meta->body_len;
+    } else if (rc == 1) {
+        session->stats.recv_timeouts += 1;
+    } else {
+        session->stats.recv_errors += 1;
+    }
+    if (session->active_ops > 0) {
+        session->active_ops -= 1;
+    }
+    if (session->closing && session->active_ops == 0) {
+        pthread_cond_broadcast(&session->idle_cond);
+    }
+    pthread_mutex_unlock(&session->mutex);
+    return rc;
+}
+
+void omnisocket_udp_session_stats_snapshot(omnisocket_udp_session_t *session, omnisocket_session_stats_t *out_stats) {
+    if (session == NULL || out_stats == NULL) {
+        return;
+    }
+    pthread_mutex_lock(&session->mutex);
+    *out_stats = session->stats;
+    pthread_mutex_unlock(&session->mutex);
+}
--- a/python/omnisocket/omnisocket_client.h
+++ b/python/omnisocket/omnisocket_client.h
@@ -2,6 +2,7 @@
 #define OMNISOCKET_PY_CLIENT_H

 #include "peer_kcp_client.h"
+#include "peer_udp_client.h"

 typedef struct omnisocket_session_stats {
    uint64_t send_calls;
@@ -23,6 +24,15 @@ typedef struct omnisocket_session {
    omnisocket_session_stats_t stats;
 } omnisocket_session_t;

+typedef struct omnisocket_udp_session {
+    pthread_mutex_t mutex;
+    pthread_cond_t idle_cond;
+    udp_client_t *client;
+    size_t active_ops;
+    int closing;
+    omnisocket_session_stats_t stats;
+} omnisocket_udp_session_t;
+
 int omnisocket_session_init(omnisocket_session_t *session);
 void omnisocket_session_destroy(omnisocket_session_t *session);

@@ -48,4 +58,27 @@ int omnisocket_session_recv_into(
 );
 void omnisocket_session_stats_snapshot(omnisocket_session_t *session, omnisocket_session_stats_t *out_stats);

+int omnisocket_udp_session_init(omnisocket_udp_session_t *session);
+void omnisocket_udp_session_destroy(omnisocket_udp_session_t *session);
+
+int omnisocket_udp_session_connect(
+    omnisocket_udp_session_t *session,
+    const char *server_addr,
+    const char *peer_id,
+    const char *bind_ip,
+    const char *bind_device,
+    int enable_timestamping
+);
+int omnisocket_udp_session_close(omnisocket_udp_session_t *session);
+int omnisocket_udp_session_send(omnisocket_udp_session_t *session, const char *to, const void *data, size_t data_len);
+int omnisocket_udp_session_recv(omnisocket_udp_session_t *session, message_t *out_msg, int timeout_ms);
+int omnisocket_udp_session_recv_into(
+    omnisocket_udp_session_t *session,
+    void *buffer,
+    size_t buffer_len,
+    udp_client_recv_meta_t *out_meta,
+    int timeout_ms
+);
+void omnisocket_udp_session_stats_snapshot(omnisocket_udp_session_t *session, omnisocket_session_stats_t *out_stats);
+
 #endif
--- a/python/tests/test_sessions.py
+++ b/python/tests/test_sessions.py
@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+import socket
+import subprocess
+import sys
+import threading
+import time
+
+import pytest
+
+
+pytestmark = pytest.mark.skipif(sys.platform != 'linux', reason='Linux-only OmniSocket extension')
+
+ROOT = Path(__file__).resolve().parents[2]
+PYTHON_ROOT = ROOT / 'python'
+if str(PYTHON_ROOT) not in sys.path:
+    sys.path.insert(0, str(PYTHON_ROOT))
+
+omnisocket = pytest.importorskip('omnisocket')
+
+CONTROL_DEFAULTS = omnisocket.CONTROL_DEFAULTS
+MSG_TYPE_BINARY = omnisocket.MSG_TYPE_BINARY
+Session = omnisocket.Session
+UdpSession = omnisocket.UdpSession
+
+
+def _reserve_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(('127.0.0.1', 0))
+        return int(sock.getsockname()[1])
+
+
+@contextmanager
+def _run_server(binary_name: str, listen_addr: str):
+    binary = ROOT / 'bin' / binary_name
+    if not binary.exists():
+        pytest.skip(f'{binary} is not built')
+
+    process = subprocess.Popen(
+        [str(binary), '-listen', listen_addr],
+        cwd=str(ROOT),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    try:
+        time.sleep(0.2)
+        yield process
+    finally:
+        process.terminate()
+        try:
+            process.wait(timeout=2.0)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait(timeout=2.0)
+
+
+def _connect_with_retry(session_cls, *, transport: str, server_addr: str, peer_id: str):
+    deadline = time.monotonic() + 3.0
+    last_error: Exception | None = None
+
+    while time.monotonic() < deadline:
+        session = session_cls()
+        try:
+            kwargs: dict[str, object] = {
+                'server_addr': server_addr,
+                'peer_id': peer_id,
+            }
+            if transport == 'kcp':
+                kwargs.update(CONTROL_DEFAULTS)
+            else:
+                kwargs['enable_timestamping'] = False
+            session.connect(**kwargs)
+            return session
+        except OSError as exc:
+            last_error = exc
+            time.sleep(0.1)
+
+    raise AssertionError(f'failed to connect {peer_id} to {server_addr}: {last_error}')
+
+
+@pytest.mark.parametrize(
+    ('transport', 'binary_name', 'session_cls'),
+    [
+        ('udp', 'udpserver', UdpSession),
+        ('kcp', 'kcpserver', Session),
+    ],
+)
+def test_control_sessions_smoke(transport: str, binary_name: str, session_cls) -> None:
+    port = _reserve_port()
+    listen_addr = f'127.0.0.1:{port}'
+    sender_id = f'pytest-{transport}-sender'
+    receiver_id = f'pytest-{transport}-receiver'
+
+    with _run_server(binary_name, listen_addr):
+        sender = _connect_with_retry(session_cls, transport=transport, server_addr=listen_addr, peer_id=sender_id)
+        receiver = _connect_with_retry(session_cls, transport=transport, server_addr=listen_addr, peer_id=receiver_id)
+
+        try:
+            assert receiver.recv(timeout_ms=20) is None
+
+            payload = b'control-packet-1'
+            sender.send(to=receiver_id, data=payload)
+            from_peer, msg_type, recv_payload = receiver.recv(timeout_ms=1000)
+            assert from_peer == sender_id
+            assert msg_type == MSG_TYPE_BINARY
+            assert recv_payload == payload
+
+            payload2 = b'control-packet-2'
+            sender.send(to=receiver_id, data=payload2)
+            recv_buffer = bytearray(128)
+            meta = receiver.recv_into(buffer=recv_buffer, timeout_ms=1000)
+            assert meta is not None
+            assert meta['from'] == sender_id
+            assert meta['msg_type'] == MSG_TYPE_BINARY
+            assert meta['body_len'] == len(payload2)
+            assert bytes(recv_buffer[: meta['body_len']]) == payload2
+
+            sender_stats = sender.stats()
+            receiver_stats = receiver.stats()
+            assert sender_stats['connected'] == 1
+            assert receiver_stats['connected'] == 1
+            assert sender_stats['send_calls'] >= 2
+            assert receiver_stats['recv_calls'] >= 2
+        finally:
+            sender.close()
+            receiver.close()
+
+
+def test_udp_session_close_interrupts_blocking_recv() -> None:
+    port = _reserve_port()
+    listen_addr = f'127.0.0.1:{port}'
+    receiver_id = 'pytest-udp-blocking-recv'
+
+    with _run_server('udpserver', listen_addr):
+        receiver = _connect_with_retry(
+            UdpSession,
+            transport='udp',
+            server_addr=listen_addr,
+            peer_id=receiver_id,
+        )
+
+        recv_error: list[BaseException] = []
+        close_error: list[BaseException] = []
+        recv_started = threading.Event()
+        recv_done = threading.Event()
+        close_done = threading.Event()
+
+        def recv_worker() -> None:
+            recv_started.set()
+            try:
+                receiver.recv()
+            except BaseException as exc:  # pragma: no cover - assertion is on thread completion
+                recv_error.append(exc)
+            finally:
+                recv_done.set()
+
+        def close_worker() -> None:
+            try:
+                receiver.close()
+            except BaseException as exc:  # pragma: no cover - assertion is on thread completion
+                close_error.append(exc)
+            finally:
+                close_done.set()
+
+        recv_thread = threading.Thread(target=recv_worker, daemon=True)
+        recv_thread.start()
+        assert recv_started.wait(timeout=1.0)
+        time.sleep(0.05)
+
+        close_thread = threading.Thread(target=close_worker, daemon=True)
+        close_thread.start()
+
+        assert close_done.wait(timeout=1.0), 'UdpSession.close() blocked while recv() was waiting'
+        assert recv_done.wait(timeout=1.0), 'UdpSession.recv() stayed blocked after close()'
+        assert not close_thread.is_alive()
+        assert not recv_thread.is_alive()
+        assert not close_error
+        assert not recv_error or isinstance(recv_error[0], OSError)