The Threading library provides general-purpose tools for working in multi-threaded environments.

Adding it to your Project

You have two options for adding this library to your project: as a framework or as source.

As a Framework

Drag the Threading.xcodeproj file into your app's Xcode project. Make sure that it is being added as a dependency.

With the library added to your project, you can now import the library header.

#import <NimbusKitThreading/NimbusKitThreading.h>

As Source

Drag all of the files from the src directory into your app.

With the library added to your project, you can now import the library header.

#import "NimbusKitThreading.h"

What's Included

Lock Store

NILockStore plays nicely with Objective-C's @synchronized for locking on a per-object basis.

In the following example, two threads need read/write access to the same data. By sharing a NILockStore instance we're able to ensure that data is safely accessed between the two threads.

NSString* const kSomeKey = @"somekey"; // Defined externally

// A single lock store object is designed to be shared by multiple threads.
NILockStore* lockStore = [NILockStore new];

Thread 1 {
  @synchronized(lockStore[kSomeKey]) {
    // Read
    id someThreadSafeObject = lockStore[kSomeKey].object;

    // Write
    lockStore[kSomeKey].object = someNewThreadSafeObject;
  }
}

Thread 2 {
  @synchronized(lockStore[kSomeKey]) {
    // Write
    lockStore[kSomeKey].object = someNewThreadSafeObject;
  }
}

Dispatch Tools

NINamedDispatchBlock is a particularly handy debugging tool that can be used to identify dispatched blocks.

NSString* threadName = [NSString stringWithFormat:@"%@ waiting for message %@",
                        NSStringFromProtocol(messageProtocol),
                        messageName];
dispatch_block_t work = ^{
  // Thread work
};

// When the block begins execution, NINamedDispatchBlock will set the name of
// the NSThread.
// Upon completion, NINamedDispatchBlock will reset the name of the thread
// to its previous value.
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0),
               NINamedDispatchBlock(threadName, work));

NIDispatchProxy is an NSProxy implementation that can be used to post invocations to an object on a separate dispatch queue. This is particularly useful if you have a delegate whose methods should only be invoked on the main thread.

Version History

1.1.0 on July 26, 2014

New dispatch features.

[new] NIDispatchTools' NINamedDispatchBlock.
[new] NIDispatchProxy for asynchronously sending messages to objects.
Renamed the library from LockStore to Threading to capture the new scope of the library.

1.0.0 on July 3, 2014

Initial release.

Includes NILockStore.

Credits

Threading was built by Jeff Verkoeyen (featherless).

Contributors

You can be the first! Open a pull request now.

License

NimbusKit's Threading is licensed under the BSD three-clause license. For a more permissive license (no redistribution of copyright notice, etc.), please contact Jeff at jverkoey@gmail.com for pricing.

NimbusKit/threading