Implement pthread API and POSIX threading support

Open pbalduino opened this issue 4 months ago • 1 comments

Goal

Implement the POSIX pthread API to provide standard threading functionality for userspace applications.

Context

With kernel threading infrastructure in place (Issue #108), we need to provide the standard POSIX pthread interface that applications expect. This enables multithreaded userspace programs and is essential for running complex applications like text editors, servers, and development tools.

Definition of Done

pthread creation/destruction: pthread_create(), pthread_exit(), pthread_join()
Thread detachment: pthread_detach() for fire-and-forget threads
Thread attributes: pthread_attr_t and attribute management functions
Thread-specific data: pthread_key_create(), pthread_setspecific(), pthread_getspecific()
Thread cleanup: pthread_cleanup_push(), pthread_cleanup_pop()
Thread identification: pthread_self(), pthread_equal()
Thread cancellation: pthread_cancel(), pthread_setcancelstate()
Thread signal handling: pthread_sigmask(), pthread_kill()
pthread library: Complete libpthread implementation

POSIX Threading API

// Core pthread functions
int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
                   void *(*start_routine)(void *), void *arg);
void pthread_exit(void *retval);
int pthread_join(pthread_t thread, void **retval);
int pthread_detach(pthread_t thread);

// Thread identification
pthread_t pthread_self(void);
int pthread_equal(pthread_t t1, pthread_t t2);

// Thread attributes
int pthread_attr_init(pthread_attr_t *attr);
int pthread_attr_destroy(pthread_attr_t *attr);
int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize);
int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize);
int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);
int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate);

// Thread-specific data
int pthread_key_create(pthread_key_t *key, void (*destructor)(void*));
int pthread_key_delete(pthread_key_t key);
int pthread_setspecific(pthread_key_t key, const void *value);
void *pthread_getspecific(pthread_key_t key);

// Thread cleanup
void pthread_cleanup_push(void (*routine)(void *), void *arg);
void pthread_cleanup_pop(int execute);

// Thread cancellation
int pthread_cancel(pthread_t thread);
int pthread_setcancelstate(int state, int *oldstate);
int pthread_setcanceltype(int type, int *oldtype);
void pthread_testcancel(void);

// Thread signals
int pthread_sigmask(int how, const sigset_t *set, sigset_t *oldset);
int pthread_kill(pthread_t thread, int sig);

Data Structures

typedef struct {
    tid_t kernel_tid;        // Kernel thread ID
    void *stack_addr;        // Stack address
    size_t stack_size;       // Stack size
    int detach_state;        // Detached or joinable
    void *exit_value;        // Thread exit value
    struct cleanup_handler *cleanup_stack;  // Cleanup handlers
    pthread_key_data_t *tsd; // Thread-specific data
    int cancel_state;        // Cancellation state
    int cancel_type;         // Cancellation type
} pthread_impl_t;

typedef pthread_impl_t* pthread_t;

typedef struct {
    size_t stack_size;       // Stack size
    void *stack_addr;        // Stack address
    int detach_state;        // Detached state
    int inherit_sched;       // Inherit scheduling
    int sched_policy;        // Scheduling policy
    struct sched_param sched_param;  // Scheduling parameters
} pthread_attr_t;

typedef struct {
    int key_id;              // Key identifier
    void (*destructor)(void*);  // Destructor function
    bool in_use;             // Key in use flag
} pthread_key_t;

Implementation Details

Thread Creation and Management

pthread_create() wraps kernel thread creation
Automatic stack allocation and management
Thread attribute processing and validation
Thread cleanup and resource management
Exit value handling and storage

Thread-Specific Data (TSD)

Per-thread key-value storage system
Automatic destructor calling on thread exit
Efficient TSD lookup and storage
Support for up to 1024 keys per thread
Thread-local storage integration

Thread Cleanup Handlers

Stack-based cleanup handler management
Automatic cleanup on thread exit
Exception-safe cleanup execution
Nested cleanup handler support
Integration with pthread_cancel()

Thread Cancellation

Deferred and asynchronous cancellation
Cancellation point implementation
Cleanup handler execution on cancellation
Thread-safe cancellation state management
Signal-based cancellation delivery

Thread Signal Handling

Per-thread signal masks
Signal delivery to specific threads
Integration with process signal handling
Thread-safe signal operations
Signal synchronization primitives

System Call Integration

// New system calls needed
int sys_thread_create(void *entry, void *arg, void *stack, size_t stack_size);
int sys_thread_exit(void *exit_value);
int sys_thread_join(tid_t tid, void **exit_value);
int sys_thread_detach(tid_t tid);
tid_t sys_thread_self(void);
int sys_thread_kill(tid_t tid, int signal);
int sys_thread_sigmask(int how, const sigset_t *set, sigset_t *oldset);

Testing Strategy

pthread creation/join stress testing
Thread-specific data functionality testing
Thread cleanup handler validation
Thread cancellation testing
Signal handling per-thread testing
Pthread attribute functionality testing
Multi-threaded application integration testing

Dependencies

Kernel threading: Issue #108 - Core threading infrastructure
Signal handling: Issue #94 - Thread signal integration
Memory management: Issue #95 - Userspace malloc for pthread structures
TLS infrastructure: Issue #88 - Thread-local storage support
System calls: Need syscall infrastructure for pthread operations

Integration Points

Integrate with libc for thread-safe operations
Add pthread support to dynamic linker
Integrate with signal handling system
Support pthread debugging in GDB
Thread-aware memory allocator integration

Security Considerations

Thread isolation and permission inheritance
Secure thread-specific data handling
Resource limit enforcement per thread
Prevention of thread-based attacks
Secure cleanup of thread resources

Files to Create/Modify

lib/pthread/pthread.c - Core pthread implementation
lib/pthread/pthread_attr.c - Thread attributes
lib/pthread/pthread_tsd.c - Thread-specific data
lib/pthread/pthread_cleanup.c - Cleanup handlers
lib/pthread/pthread_cancel.c - Thread cancellation
include/pthread.h - POSIX pthread interface
lib/pthread/pthread_internal.h - Internal pthread definitions

Performance Goals

pthread_create() latency < 100μs
pthread_join() latency < 50μs
TSD access < 10ns per operation
Minimal memory overhead per pthread
Low contention on pthread operations

Error Handling

EAGAIN for resource exhaustion
EINVAL for invalid parameters
ESRCH for non-existent threads
EDEADLK for join deadlock detection
EPERM for permission violations

POSIX Compliance

Full POSIX.1-2017 pthread compliance
Proper error code handling
Standard behavior for edge cases
Compatibility with existing pthread applications
Support for pthread-based libraries

Usage Examples

#include <pthread.h>

void* worker_thread(void* arg) {
    // Thread-specific data
    pthread_setspecific(my_key, worker_data);
    
    // Cleanup handler
    pthread_cleanup_push(cleanup_function, cleanup_data);
    
    // Do work...
    
    pthread_cleanup_pop(1);  // Execute cleanup
    return result;
}

int main() {
    pthread_t thread;
    pthread_attr_t attr;
    
    // Set thread attributes
    pthread_attr_init(&attr);
    pthread_attr_setstacksize(&attr, 32768);
    
    // Create thread
    pthread_create(&thread, &attr, worker_thread, work_data);
    
    // Wait for completion
    void *result;
    pthread_join(thread, &result);
    
    pthread_attr_destroy(&attr);
    return 0;
}

Related Issues

Enables multithreaded applications on meniOS
Required for modern text editors and IDEs
Foundation for thread-safe C library implementation
Critical for server applications and databases
Enables parallel programming paradigms

Priority

HIGH - Critical for GCC/self-hosting milestone

Justification

pthread API is essential for:

GCC Compilation: GCC and many build tools require threading support
Self-Hosting: Required before compiling complex userspace applications
Foundation: Blocks #110 (thread-safe libc) which is also critical
Userspace Development: Enables multithreaded applications (editors, servers, dev tools)

Dependency Chain

#108 (Kernel threading) ✅ COMPLETE
  ↓
#109 (pthread API) ← YOU ARE HERE  
  ↓
#110 (thread-safe libc) ← HIGH priority
  ↓
GCC/self-hosting milestone

Impact

Without pthread support:

❌ Cannot compile GCC natively
❌ Cannot run multithreaded build tools (make -j)
❌ Limited userspace application development
❌ Blocks thread-safe libc (#110)

Estimated Effort: 6-8 weeks part-time

Related Issues:

#108 (Kernel threading infrastructure) ✅ COMPLETE
#110 (Thread-safe libc) - blocked by this issue
#190 (TCC port) - may benefit from threading
GCC self-hosting milestone

Sep 28 '25 15:09 pbalduino