Skip to content
Locksmith
C CMake C++
Latest commit f1a85b2 Jan 28, 2016 Colin Patrick McCabe Merge pull request #5 from mithris/fix_memmove_issue
lk_remove_sorted: fix issue where memmove could write to an invalid location
Failed to load latest commit information.
cmake_modules
.gitignore
AUTHORS
CMakeLists.txt
LICENSE.txt
README.md
backtrace.h
config.h
config.h.cmake use libunwind rather than the glibc backtrace function Apr 28, 2013
configure
error.c print backtraces for many errors Jul 14, 2013
error.h
error_unit.c add the ability to detect more cond variable errors Jul 14, 2013
handler.c
handler.h
ignore_unit.c
libc_backtrace.c add ignored frame patterns, fix libc backtrace Jun 7, 2013
libunwind_backtrace.c add ignored frame patterns, fix libc backtrace Jun 7, 2013
linux_platform.c
lksmith.c
lksmith.h
lock_unit.c
mem.c
mem.h move xcalloc out of test, into mem. Dec 8, 2012
platform.h
posix_platform.c
simple_unit.c
test.c
test.h
thread_unit.c
tree.h
util.c reorganization Nov 24, 2012
util.h

README.md

Locksmith

Locksmith is a library for debugging locking in C, C++, or Objective C programs.

It's designed to catch common locking errors at runtime that might otherwise lead to deadlocks or crashes. Locksmith is built on top of pthreads.

How do I build the source code?

./configure
make
sudo make install

How to use Locksmith

Using locksmith is simple. You do not need to recompile your program. Just run your program with the LD_PRELOAD environment variable set to the locksmith library. For example,

LKSMITH_LOG=syslog LD_PRELOAD=/path/to/liblksmith.so /bin/ls

What kinds of errors does Locksmith catch?

  1. Locking inversions. For example, if one thread locks mutex A and then tries to lock mutex B, and another thread locks mutex B and then tries to locks mutex A.

  2. Freeing a mutex, spinlock, or condition variable that you currently hold. In the pthreads library, freeing a mutex, spinlock, or condition variable that you currently hold can cause undefined behavior. You must release it first. Locksmith issues an error message in this case.

  3. Unlocking a mutex from a different thread than the one which locked it. This is another scenario which triggers undefined behavior in pthreads, but which Locksmith turns into a hard error.

  4. Calling pthread_cond_wait on something that isn't a mutex locked by the current thread.

  5. Simultaneously calling pthread_cond_wait on the same condition variable using different mutexes.

What choices are available for LKSMITH_LOG?

LKSMITH_LOG=syslog

This will redirect all output to syslog.

LKSMITH_LOG=stderr

This will redirect all output to standard error.

LKSMITH_LOG=stdout

This will redirect all output to standard output.

LKSMITH_LOG=file:///tmp/foo

This will redirect all output to /tmp/foo. Substitute your own file name as appropriate.

What languages and libraries is Locksmith compatible with?

Locksmith should be compatible with every library built on top of pthreads in C or C++. This includes boost::mutex, KDE's QMutex, glib's Glib::Mutex, and so forth. Locksmith has no problems with global constructors or destructors in C++. Locksmith also works with mutexes that have been initialized statically with PTHREAD_MUTEX_INITIALIZER. Finally, Locksmith handles pthreads mutexes created and used in a shared library independent of the main executable.

What license is Locksmith under?

Locksmith is released under the 2-clause BSD license. See LICENSE.txt for details.

TODO

  • Expose the lock APIs to client code. This will make Locksmith usable in code that implements its own locking primitives.
  • Support pthread rwlocks
  • Support pthread barriers
  • Add the ability to dump out debugging information about the state of all locks on command.
  • Support thread cancellation (?)
  • Support POSIX semaphores
  • Add a way to suppress deadlock warnings through the use of compile-time annotations.
  • Add the ability to name mutexes and threads through the use of compile-time annotations.
  • Better support for debugging cross-process mutexes and spin-locks (perhaps by putting Locksmith globals into a shared memory segment?) This is tricky because cross-process locks won't have the same memory address in different processes.

Contact information

Colin Patrick McCabe cmccabe@alumni.cmu.edu

Something went wrong with that request. Please try again.