libc: implement pthread_mutex_timedlock and pthread_mutex_clocklock

Both were stubs returning EINVAL, so code that uses a bounded mutex acquire
(common in databases and glibc-based libraries) could not run.

OSv's lockfree mutex has no native timed acquire, so implement them by polling
try_lock() with a short (50 us) sleep between attempts until the absolute
deadline, returning 0 on success or ETIMEDOUT when the deadline passes. The
uncontended case takes the try_lock() fast path with no sleeping.
pthread_mutex_clocklock supports CLOCK_REALTIME and CLOCK_MONOTONIC (converting
the deadline against the right clock) and returns EINVAL for any other clock; a
malformed timespec also returns EINVAL.

This is a poll-and-backoff acquire rather than a native timed wait, which is
fine for the rare contended timedlock; the lockfree mutex could grow a real
timed wait later if it ever needs to be tight.

Add tests/tst-pthread-timedlock.cc: uncontended success, contended timeout
(ETIMEDOUT from another thread while the main thread holds the lock, no
deadlock), success after unlock, CLOCK_MONOTONIC clocklock, and the EINVAL clock
path. Passes on OSv under KVM; tst-pthread continues to pass.

Fixes #834

Closes #1426

Author: gburd

libc/pthread.cc

@@ -452,19 +452,58 @@ int pthread_mutex_trylock(pthread_mutex_t *m)
     return 0;
 }
 
+// Try to lock @m, spinning-with-backoff until the absolute deadline given by
+// @abs_timeout on clock @clock.  OSv's lockfree mutex has no native timed lock,
+// so we poll try_lock() with a short sleep between attempts.  Returns 0 on
+// success or ETIMEDOUT if the deadline passes first.
+//
+// ponytail: poll+backoff, not a native timed acquire.  Fine for the rare
+// contended timedlock; if it ever needs to be tight, add a timed wait to the
+// lockfree mutex itself.
+static int mutex_timedlock_until(pthread_mutex_t *m, clockid_t clock,
+                                 const struct timespec *abs_timeout)
+{
+    if (from_libc(m)->try_lock()) {
+        return 0;   // uncontended fast path
+    }
+    if (!abs_timeout || abs_timeout->tv_nsec < 0 ||
+        abs_timeout->tv_nsec >= 1000000000) {
+        return EINVAL;
+    }
+
+    auto deadline_ns = std::chrono::seconds(abs_timeout->tv_sec) +
+                       std::chrono::nanoseconds(abs_timeout->tv_nsec);
+    auto now = [clock]() -> std::chrono::nanoseconds {
+        if (clock == CLOCK_MONOTONIC) {
+            return osv::clock::uptime::now().time_since_epoch();
+        }
+        return osv::clock::wall::now().time_since_epoch();
+    };
+
+    while (now() < deadline_ns) {
+        if (from_libc(m)->try_lock()) {
+            return 0;
+        }
+        sched::thread::sleep(std::chrono::microseconds(50));
+    }
+    // One last attempt right at the deadline.
+    return from_libc(m)->try_lock() ? 0 : ETIMEDOUT;
+}
+
 int pthread_mutex_timedlock(pthread_mutex_t *m,
         const struct timespec *abs_timeout)
 {
-    WARN_STUBBED();
-    return EINVAL;
+    return mutex_timedlock_until(m, CLOCK_REALTIME, abs_timeout);
 }
 
 int pthread_mutex_clocklock(pthread_mutex_t *m,
                             clockid_t clock,
                             const struct timespec *abs_timeout)
 {
-    WARN_STUBBED();
-    return EINVAL;
+    if (clock != CLOCK_REALTIME && clock != CLOCK_MONOTONIC) {
+        return EINVAL;
+    }
+    return mutex_timedlock_until(m, clock, abs_timeout);
 }
 
 int pthread_mutex_unlock(pthread_mutex_t *m)

modules/tests/Makefile

@@ -120,6 +120,7 @@ tests := tst-pthread.so misc-ramdisk.so tst-vblk.so tst-bsd-evh.so \
 	tst-fpu.so tst-preempt.so tst-tracepoint.so tst-hub.so \
 	misc-console.so misc-leak.so misc-readbench.so misc-mmap-anon-perf.so \
 	tst-mmap-file.so misc-mmap-big-file.so tst-mmap.so tst-huge.so \
+	tst-pthread-timedlock.so \
 	tst-prctl.so \
 	tst-mmap-file-cow.so \
 	tst-elf-permissions.so misc-mutex.so misc-sockets.so tst-condvar.so \

tests/tst-pthread-timedlock.cc

@@ -0,0 +1,76 @@
+/*
+ * Copyright (C) 2026 Waldemar Kozaczuk
+ *
+ * This work is open source software, licensed under the terms of the
+ * BSD license as described in the LICENSE file in the top-level directory.
+ */
+
+// Exercises pthread_mutex_timedlock / pthread_mutex_clocklock.
+// Built and run on the OSv test image.
+
+#include <pthread.h>
+#include <time.h>
+#include <errno.h>
+
+#include <cassert>
+#include <iostream>
+
+static struct timespec deadline_in(clockid_t clk, long ms)
+{
+    struct timespec ts;
+    clock_gettime(clk, &ts);
+    ts.tv_nsec += (ms % 1000) * 1000000L;
+    ts.tv_sec += ms / 1000 + ts.tv_nsec / 1000000000L;
+    ts.tv_nsec %= 1000000000L;
+    return ts;
+}
+
+struct tl_arg { pthread_mutex_t *m; int result; };
+
+static void *hold_attempt(void *p)
+{
+    auto *a = static_cast<tl_arg *>(p);
+    struct timespec ts;
+    clock_gettime(CLOCK_REALTIME, &ts);
+    ts.tv_nsec += 200000000L;   // 200 ms
+    if (ts.tv_nsec >= 1000000000L) { ts.tv_sec++; ts.tv_nsec -= 1000000000L; }
+    a->result = pthread_mutex_timedlock(a->m, &ts);
+    return nullptr;
+}
+
+int main()
+{
+    std::cerr << "Running pthread timedlock tests\n";
+    pthread_mutex_t m = PTHREAD_MUTEX_INITIALIZER;
+
+    // Uncontended: timedlock succeeds immediately.
+    struct timespec t = deadline_in(CLOCK_REALTIME, 1000);
+    assert(pthread_mutex_timedlock(&m, &t) == 0);
+
+    // Held by us: a second timedlock (on another thread) must time out rather
+    // than deadlock.
+    tl_arg a { &m, -999 };
+    pthread_t th;
+    pthread_create(&th, nullptr, hold_attempt, &a);
+    pthread_join(th, nullptr);
+    assert(a.result == ETIMEDOUT);   // could not acquire; we still hold it
+
+    pthread_mutex_unlock(&m);
+
+    // After unlock, timedlock succeeds again.
+    t = deadline_in(CLOCK_REALTIME, 1000);
+    assert(pthread_mutex_timedlock(&m, &t) == 0);
+    pthread_mutex_unlock(&m);
+
+    // clocklock with CLOCK_MONOTONIC: uncontended success.
+    t = deadline_in(CLOCK_MONOTONIC, 1000);
+    assert(pthread_mutex_clocklock(&m, CLOCK_MONOTONIC, &t) == 0);
+    pthread_mutex_unlock(&m);
+
+    // clocklock with an unsupported clock -> EINVAL.
+    t = deadline_in(CLOCK_MONOTONIC, 1000);
+    assert(pthread_mutex_clocklock(&m, 99, &t) == EINVAL);
+
+    std::cerr << "pthread timedlock tests PASSED\n";
+    return 0;
+}