Note

The project is currently under migration to CMake

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:

• 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. Runti me 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.