What is it

BThread is a lightweight user-level threading library written in C. It provides a simple and efficient cooperative threading model with support for common synchronization primitives including mutexes, semaphores, condition variables, barriers, and thread-safe queues.

On what hardware does it run?

The library runs on Linux, macOS, and Windows systems with x86_64 architecture. It uses setjmp/longjmp for context switching and is designed to be portable across POSIX-compliant systems.

Documentation

Core API:

bthread_create()     // Create a new thread
bthread_join()       // Wait for a thread to terminate
bthread_yield()      // Yield execution to another thread
bthread_exit()       // Terminate the calling thread
bthread_sleep()      // Sleep for specified milliseconds
bthread_cancel()     // Request thread cancellation
bthread_testcancel() // Check for cancellation requests

Synchronization Primitives:

• tmutex: Mutual exclusion locks
• tsemaphore: Counting semaphores
• tcondition: Condition variables
• tbarrier: Thread barriers

For detailed API documentation, see the header files in the include/ directory.

Installation

Building the library:

make              # Build default demo and shared library
make lib          # Build only the shared library
make demos        # Build all demo programs
make test         # Build and run tests
make clean        # Clean build artifacts

The shared library will be built in the lib/ directory:

• Linux: libbthread.so
• macOS: libbthread.dylib
• Windows: bthread.dll

To use the library in your project:

1. Include the header: #include <bthread.h>
2. Link against the shared library: -lbthread
3. Add the include path: -I/path/to/libbthread/include
4. Add the library path: -L/path/to/libbthread/lib

Examples: See the demos/ directory for complete examples including:

• Producer-Consumer patterns
• Dining Philosophers problem
• Reader-Writer locks
• Sleeping Barber problem

If something goes wrong

Common issues:

1. Compilation errors:

   • Ensure you have GCC installed and updated
   • Check that all source files are present
   • Verify include paths are correct

2. Linking errors:

   • Make sure the library path is in your LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS)
   • Verify the shared library was built successfully

3. Runtime issues:

   • Check that threads are properly synchronized
   • Ensure thread_yield() is called regularly in cooperative scheduling
   • Verify all mutexes/semaphores are properly initialized

For bugs and issues, please report them at the project repository.

Copyright

License: MIT License

Authors:

• Luca Mazza (C) 2025

This software is provided "as is" without warranty of any kind. See the LICENSE file for complete terms and conditions.