Skip to content

README.md

Latest commit

 

History

History
117 lines (84 loc) · 3.47 KB

README.md

File metadata and controls

117 lines (84 loc) · 3.47 KB

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.