products/swift-bindings/llbuild.swift - third_party/swift-llbuild - Git at Google

 // This source file is part of the Swift.org open source project
 //
 // Copyright 2015 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See http://swift.org/LICENSE.txt for license information
 // See http://swift.org/CONTRIBUTORS.txt for Swift project authors

 // This file contains Swift bindings for the llbuild C API.

 import Foundation

 enum DatabaseError: Error {
   case AttachFailure(message: String)
 }

 private func stringFromData(data: llb_data_t) -> String {
   // Convert as a UTF8 string, if possible.
   let tmp = NSData(bytes: unsafeBitCast(data.data, to: UnsafeRawPointer.self), length: Int(data.length))
   if let str = String(data: tmp as Data, encoding: String.Encoding.utf8) {
     return str
   }

   // Otherwise, return a string representation of the bytes.
   return String(describing: [UInt8](UnsafeBufferPointer(start: data.data, count: Int(data.length))))
 }

 private func stringFromUInt8Array(_ data: [UInt8]) -> String {
   // Convert as a UTF8 string, if possible.
   let tmp = NSData(bytes: data, length: data.count)
   if let str = String(data: tmp as Data, encoding: String.Encoding.utf8) {
     return str
   }

   // Otherwise, return a string representation of the bytes.
   return String(describing: data)
 }

 /// Key objects are used to identify rules that can be built.
 public struct Key: CustomStringConvertible, Equatable, Hashable {
   public let data: [UInt8]

   // MARK: CustomStringConvertible Conformance

   public var description: String {
     return "<Key: '\(toString())'>"
   }

   // MARK: Hashable Conformance

   public var hashValue: Int {
     // FIXME: Use a real hash function.
     var result = data.count
     for c in data {
       result = result*31 + Int(c)
     }
     return result
   }

   // MARK: Implementation

   public init(_ data: [UInt8]) { self.data = data }
   public init(_ str: String) { self.init(Array(str.utf8)) }

   /// Convert to a string representation.
   public func toString() -> String {
     return stringFromUInt8Array(self.data)
   }

   /// Create a Key object from an llb_data_t.
   fileprivate static func fromInternalData(_ data: llb_data_t) -> Key {
     return Key([UInt8](UnsafeBufferPointer(start: data.data, count: Int(data.length))))
   }

   /// Provide a Key contents as an llb_data_t pointer.
   fileprivate func withInternalDataPtr<T>(closure: (UnsafePointer<llb_data_t>) -> T) -> T {
     return data.withUnsafeBufferPointer { (dataPtr: UnsafeBufferPointer<UInt8>) -> T in
         var value = llb_data_t(length: UInt64(self.data.count), data: dataPtr.baseAddress)
         return withUnsafePointer(to: &value, closure)
     }
   }
 }

 public func ==(lhs: Key, rhs: Key) -> Bool {
   return lhs.data == rhs.data
 }

 /// Value objects are the result of building rules.
 public struct Value: CustomStringConvertible {
   public let data: [UInt8]

   public var description: String {
     return "<Value: '\(toString())'>"
   }

   public init(_ data: [UInt8]) { self.data = data }
   public init(_ str: String) { self.init(Array(str.utf8)) }

   /// Convert to a string representation.
   public func toString() -> String {
     return stringFromUInt8Array(self.data)
   }

   /// Create a Value object from an llb_data_t.
   fileprivate static func fromInternalData(_ data: llb_data_t) -> Value {
     return Value([UInt8](UnsafeBufferPointer(start: data.data, count: Int(data.length))))
   }

   /// Provide a Value contents as an llb_data_t pointer.
   fileprivate func withInternalDataPtr<T>(closure: (UnsafePointer<llb_data_t>) -> T) -> T {
     return data.withUnsafeBufferPointer { (dataPtr: UnsafeBufferPointer<UInt8>) -> T in
         var value = llb_data_t(length: UInt64(self.data.count), data: dataPtr.baseAddress)
       return withUnsafePointer(to: &value, closure)
     }
   }

   /// Create a Value object by providing an pointer to write the output into.
   ///
   /// \param closure The closure to execute with a pointer to a llb_data_t to
   /// use. The structure *must* be filled in by the closure.
   ///
   /// \return The output Value.
   fileprivate static func fromInternalDataOutputPtr(closure: (UnsafeMutablePointer<llb_data_t>) -> Void) -> Value {
     var data = llb_data_t()
     withUnsafeMutablePointer(to: &data, closure)
     return Value.fromInternalData(data)
   }
 }

 /// Enumeration describing the possible status of a Rule, used by \see
 /// Rule.updateStatus().
 public enum RuleStatus {
   /// Indicates the rule is being scanned.
 case IsScanning
   /// Indicates the rule is up-to-date, and doesn't need to run.
 case IsUpToDate
   /// Indicates the rule was run, and is now complete.
 case IsComplete
 }

 /// A rule represents an individual element of computation that can be performed
 /// by the build engine.
 ///
 /// Each rule is identified by a unique key and the value for that key can be
 /// computed to produce a result, and supplies a set of callbacks that are used
 /// to implement the rule's behavior.
 ///
 /// The computation for a rule is done by invocation of its \see Action
 /// callback, which is responsible for creating a Task object which will manage
 /// the computation.
 ///
 /// All callbacks for the Rule are always invoked synchronously on the primary
 /// BuildEngine thread.
 public protocol Rule {
   /// Called to create the task to build the rule, when necessary.
   func createTask() -> Task

   /// Called to check whether the previously computed value for this rule is
   /// still valid.
   ///
   /// This callback is designed for use in synchronizing values which represent
   /// state managed externally to the build engine. For example, a rule which
   /// computes something on the file system may use this to verify that the
   /// computed output has not changed since it was built.
   func isResultValid(_ priorValue: Value) -> Bool

   /// Called to indicate a change in the rule status.
   func updateStatus(_ status: RuleStatus)
 }

 /// Protocol extension for default Rule methods.
 public extension Rule {
   final func isResultValid(_ priorValue: Value) -> Bool { return true }
   final func updateStatus(_ status: RuleStatus) { }
 }

 /// A task object represents an abstract in-progress computation in the build
 /// engine.
 ///
 /// The task represents not just the primary computation, but also the process
 /// of starting the computation and necessary input dependencies. Tasks are
 /// expected to be created in response to \see BuildEngine requests to initiate
 /// the production of particular result value.
 ///
 /// The creator may use \see TaskBuildEngine.taskNeedsInput() to specify input
 /// dependencies on the Task. The Task itself may also specify additional input
 /// dependencies dynamically during the execution of \see Task.start() or \see
 /// Task.provideValue().
 ///
 /// Once a task has been created and registered, the BuildEngine will invoke
 /// \see Task::start() to initiate the computation. The BuildEngine will provide
 /// the in progress task with its requested inputs via \see
 /// Task.provideValue().
 ///
 /// After all inputs requested by the Task have been delivered, the BuildEngine
 /// will invoke \see Task.inputsAvailable() to instruct the Task it should
 /// complete its computation and provide the output. The Task is responsible for
 /// providing the engine with the computed value when ready using \see
 /// TaskBuildEngine.taskIsComplete().
 public protocol Task {
   /// Executed by the build engine when the task should be started.
   func start(_ engine: TaskBuildEngine)

   /// Invoked by the build engine to provide an input value as it becomes
   /// available.
   ///
   /// \param inputID The unique identifier provided to the build engine to
   /// represent this input when requested in \see
   /// TaskBuildEngine.taskNeedsInput().
   ///
   /// \param value The computed value for the given input.
   func provideValue(_ engine: TaskBuildEngine, inputID: Int, value: Value)

   /// Executed by the build engine to indicate that all inputs have been
   /// provided, and the task should begin its computation.
   ///
   /// The task is expected to call \see TaskBuildEngine.taskIsComplete() when it is
   /// done with its computation.
   ///
   /// It is an error for any client to request an additional input for a task
   /// after the last requested input has been provided by the build engine.
   func inputsAvailable(_ engine: TaskBuildEngine)
 }

 /// Delegate interface for use with the build engine.
 public protocol BuildEngineDelegate {
   /// Get the rule to use for the given Key.
   ///
   /// The delegate *must* provide a rule for any possible key that can be
   /// requested (either by a client, through \see BuildEngine.build(), or via a
   /// Task through mechanisms such as \see TaskBuildEngine.taskNeedsInput(). If a
   /// requested Key cannot be supplied, the delegate should provide a dummy rule
   /// that the client can translate into an error.
   func lookupRule(_ key: Key) -> Rule
 }

 /// Wrapper to allow passing an opaque pointer to a protocol type.
 //
 // FIXME: Why do we need this, why can't we get a pointer to the protocol
 // typed object?
 private class Wrapper<T> {
   let item: T
   init(_ item: T) { self.item = item }
 }

 /// This protocol encapsulates the API that a task can use to communicate with
 /// the build engine.
 public protocol TaskBuildEngine {
   var engine: BuildEngine { get }

   /// Specify that the task depends upon the result of computing \arg key.
   ///
   /// The result, when available, will be provided to the task via \see
   /// Task.provideValue(), supplying the provided \arg inputID to allow the task
   /// to identify the particular input.
   ///
   /// NOTE: It is an unchecked error for a task to request the same input value
   /// multiple times.
   ///
   /// \param inputID An arbitrary value that may be provided by the client to
   /// use in efficiently associating this input.
   func taskNeedsInput(_ key: Key, inputID: Int)

   /// Specify that the task must be built subsequent to the computation of \arg
   /// key.
   ///
   /// The value of the computation of \arg key is not available to the task, and
   /// the only guarantee the engine provides is that if \arg key is computed
   /// during a build, then task will not be computed until after it.
   func taskMustFollow(_ key: Key)

   /// Inform the engine of an input dependency that was discovered by the task
   /// during its execution, a la compiler generated dependency files.
   ///
   /// This call may only be made after a task has received all of its inputs;
   /// inputs discovered prior to that point should simply be requested as normal
   /// input dependencies.
   ///
   /// Such a dependency is not used to provide additional input to the task,
   /// rather it is a way for the task to report an additional input which should
   /// be considered the next time the rule is evaluated. The expected use case
   /// for a discovered dependency is is when a processing task cannot predict
   /// all of its inputs prior to being run, but can presume that any unknown
   /// inputs already exist. In such cases, the task can go ahead and run and can
   /// report the all of the discovered inputs as it executes. Once the task is
   /// complete, these inputs will be recorded as being dependencies of the task
   /// so that it will be recomputed when any of the inputs change.
   ///
   /// It is legal to call this method from any thread, but the caller is
   /// responsible for ensuring that it is never called concurrently for the same
   /// task.
   func taskDiscoveredDependency(_ key: Key)

   /// Indicate that the task has completed and provide its resulting value.
   ///
   /// It is legal to call this method from any thread.
   ///
   /// \param value The new value for the task's rule.
   ///
   /// \param forceChange If true, treat the value as changed and trigger
   /// dependents to rebuild, even if the value itself is not different from the
   /// prior result.
   func taskIsComplete(_ result: Value, forceChange: Bool)
 }

 /// Single concrete implementation of the TaskBuildEngine protocol.
 private class TaskWrapper: CustomStringConvertible, TaskBuildEngine {
   let engine: BuildEngine
   let task: Task
   var taskInternal: OpaquePointer?

   var description: String {
     return "<TaskWrapper engine:\(engine), task:\(task)>"
   }

   init(_ engine: BuildEngine, _ task: Task) {
     self.engine = engine
     self.task = task
   }

   func taskNeedsInput(_ key: Key, inputID: Int) {
     engine.taskNeedsInput(self, key: key, inputID: inputID)
   }

   func taskMustFollow(_ key: Key) {
     engine.taskMustFollow(self, key: key)
   }

   func taskDiscoveredDependency(_ key: Key) {
     engine.taskDiscoveredDependency(self, key: key)
   }

   func taskIsComplete(_ result: Value, forceChange: Bool = false) {
     engine.taskIsComplete(self, result: result, forceChange: forceChange)
   }
 }

 /// A build engine supports fast, incremental, persistent, and parallel
 /// execution of computational graphs.
 ///
 /// Computational elements in the graph are modeled by \see Rule objects, which
 /// are assocated with a specific \see Key, and which can be executed to produce
 /// an output \see Value for that key.
 ///
 /// Rule objects are evaluated by first invoking their action to produce a \see
 /// Task object which is responsible for the live execution of the
 /// computation. The Task object can interact with the BuildEngine to request
 /// inputs or to notify the engine of its completion, and receives various
 /// callbacks from the engine as the computation progresses.
 ///
 /// The engine itself executes using a deterministic, serial operation, but it
 /// supports parallel computation by allowing the individual Task objects to
 /// defer their own computation to signal the BuildEngine of its completion on
 /// alternate threads.
 ///
 /// To support persistence, the engine allows attaching a database (\see
 /// attachDB()) which can be used to record the prior results of evaluating Rule
 /// instances.
 public class BuildEngine {
   /// The client delegate.
   private var delegate: BuildEngineDelegate

   /// The internal llbuild build engine.
   private var _engine: OpaquePointer?

   /// Our llbuild engine delegate object.
   private var _delegate = llb_buildengine_delegate_t()

   /// The number of rules which have been defined.
   public var numRules: Int = 0

   public init(delegate: BuildEngineDelegate) {
     self.delegate = delegate

     // Initialize the delegate.
     _delegate.context = unsafeBitCast(Unmanaged.passUnretained(self), to: UnsafeMutableRawPointer.self)

     _delegate.lookup_rule = { BuildEngine.toEngine($0!).lookupRule($1!, $2!) }
     // FIXME: Include cycleDetected callback.

     // Create the engine.
     _engine = llb_buildengine_create(_delegate)
   }

   deinit {
     if _engine != nil {
         close()
     }
   }

   public func close() {
     assert(_engine != nil)
     llb_buildengine_destroy(_engine)
     _engine = nil
   }

   /// Build the result for a particular key.
   public func build(key: Key) -> Value {
     return Value.fromInternalDataOutputPtr { resultPtr in
       key.withInternalDataPtr { llb_buildengine_build(self._engine, $0, resultPtr) }
     }
   }

   /// Attach a database for persisting build state.
   ///
   /// A database should only be attached immediately after creating the engine,
   /// it is an error to attach a database after adding rules or initiating any
   /// builds, or to attempt to attach multiple databases.
   public func attachDB(path: String, schemaVersion: Int = 0) throws {
     let errorPtr = UnsafeMutablePointer<UnsafeMutablePointer<Int8>?>.allocate(capacity: 1)
     defer { errorPtr.deinitialize(count: 1) }

     // FIXME: Why do I have to name the closure signature here?
     var errorMsgOpt: String? = nil
     Key(path).withInternalDataPtr { (ptr) -> Void in
       if !llb_buildengine_attach_db(self._engine, ptr, UInt32(schemaVersion), errorPtr) {
         // If there was an error, report it.
         if let errorPointee = errorPtr.pointee {
             errorMsgOpt = String(cString: errorPointee)
         }
       }
     }
     // Throw the error, if found.
     if let errorMsg = errorMsgOpt {
       throw DatabaseError.AttachFailure(message: errorMsg)
     }
   }

   /// MARK: Internal Task-Only API

   fileprivate func taskNeedsInput(_ taskWrapper: TaskWrapper, key: Key, inputID: Int) {
     key.withInternalDataPtr { keyPtr in
       llb_buildengine_task_needs_input(self._engine, taskWrapper.taskInternal, keyPtr, UInt(inputID))
     }
   }

   fileprivate func taskMustFollow(_ taskWrapper: TaskWrapper, key: Key) {
     key.withInternalDataPtr { keyPtr in
       llb_buildengine_task_must_follow(self._engine, taskWrapper.taskInternal, keyPtr)
     }
   }

   fileprivate func taskDiscoveredDependency(_ taskWrapper: TaskWrapper, key: Key) {
     key.withInternalDataPtr { keyPtr in
       llb_buildengine_task_discovered_dependency(self._engine, taskWrapper.taskInternal, keyPtr)
     }
   }

   fileprivate func taskIsComplete(_ taskWrapper: TaskWrapper, result: Value, forceChange: Bool = false) {
     result.withInternalDataPtr { dataPtr in
       llb_buildengine_task_is_complete(self._engine, taskWrapper.taskInternal, dataPtr, forceChange)
     }
   }

   /// MARK: Internal Delegate Implementation

   /// Helper function for getting the engine from the delegate context.
   static fileprivate func toEngine(_ context: UnsafeMutableRawPointer) -> BuildEngine {
     return Unmanaged<BuildEngine>.fromOpaque(context).takeUnretainedValue()
   }

   /// Helper function for getting the rule from a rule delegate context.
   static fileprivate func toRule(_ context: UnsafeMutableRawPointer) -> Rule {
     return Unmanaged<Wrapper<Rule>>.fromOpaque(context).takeUnretainedValue().item
   }

   /// Helper function for getting the task from a task delegate context.
   static fileprivate func toTaskWrapper(_ context: UnsafeMutableRawPointer) -> TaskWrapper {
     return Unmanaged<TaskWrapper>.fromOpaque(context).takeUnretainedValue()
   }

   fileprivate func lookupRule(_ key: UnsafePointer<llb_data_t>, _ ruleOut: UnsafeMutablePointer<llb_rule_t>) {
     numRules += 1

     // Get the rule from the client.
     let rule = delegate.lookupRule(Key.fromInternalData(key.pointee))

     // Fill in the output structure.
     //
     // FIXME: We need a deallocation callback in order to ensure this is released.
     ruleOut.pointee.context = unsafeBitCast(Unmanaged.passRetained(Wrapper(rule)), to: UnsafeMutableRawPointer.self)
     ruleOut.pointee.create_task = { (context, engineContext) -> OpaquePointer! in
       let rule = BuildEngine.toRule(context!)
       let engine = BuildEngine.toEngine(engineContext!)
       return engine.ruleCreateTask(rule)
     }
     ruleOut.pointee.is_result_valid = { (context, engineContext, internalRule, value) -> Bool in
       let rule = BuildEngine.toRule(context!)
       return rule.isResultValid(Value.fromInternalData(value!.pointee))
     }
     ruleOut.pointee.update_status =  { (context, engineContext, status) in
       let rule = BuildEngine.toRule(context!)
       let status = { (kind: llb_rule_status_kind_t) -> RuleStatus in
         switch kind.rawValue {
           case llb_rule_is_scanning.rawValue: return .IsScanning
           case llb_rule_is_up_to_date.rawValue: return .IsUpToDate
           case llb_rule_is_complete.rawValue: return .IsComplete
           default:
             fatalError("unknown status kind")
         } }(status)
       return rule.updateStatus(status)
     }
   }

   private func ruleCreateTask(_ rule: Rule) -> OpaquePointer {
     // Create the task.
     let task = rule.createTask()

     // Create the task wrapper.
     //
     // Note that the wrapper here is serving two purposes, it is providing a way
     // to communicate the internal task object to clients, and it is providing a
     // way to segregate the Task-only API from the rest of the BuildEngine API.
     let taskWrapper = TaskWrapper(self, task)

     // Create the task delegate.
     //
     // FIXME: Separate the delegate from the context pointer.
     var taskDelegate = llb_task_delegate_t()
     // FIXME: We need a deallocation callback in order to ensure this is released.
     taskDelegate.context = unsafeBitCast(Unmanaged.passRetained(taskWrapper), to: UnsafeMutableRawPointer.self)
     taskDelegate.start = { (context, engineContext, internalTask) in
       let taskWrapper = BuildEngine.toTaskWrapper(context!)
       taskWrapper.task.start(taskWrapper)
     }
     taskDelegate.provide_value = { (context, engineContext, internalTask, inputID, value) in
       let taskWrapper = BuildEngine.toTaskWrapper(context!)
       taskWrapper.task.provideValue(taskWrapper, inputID: Int(inputID), value: Value.fromInternalData(value!.pointee))
     }
     taskDelegate.inputs_available = { (context, engineContext, internalTask) in
       let taskWrapper = BuildEngine.toTaskWrapper(context!)
       taskWrapper.task.inputsAvailable(taskWrapper)
     }

     // Create the internal task.
     taskWrapper.taskInternal = llb_task_create(taskDelegate)

     // FIXME: Why do we have both of these, it is kind of annoying. It makes
     // some amount of sense in the C++ API, but the C API should probably just
     // collapse them.
     return llb_buildengine_register_task(self._engine, taskWrapper.taskInternal)
   }
 }
	// This source file is part of the Swift.org open source project
	//
	// Copyright 2015 Apple Inc. and the Swift project authors
	// Licensed under Apache License v2.0 with Runtime Library Exception
	//
	// See http://swift.org/LICENSE.txt for license information
	// See http://swift.org/CONTRIBUTORS.txt for Swift project authors

	// This file contains Swift bindings for the llbuild C API.

	import Foundation

	enum DatabaseError: Error {
	case AttachFailure(message: String)
	}

	private func stringFromData(data: llb_data_t) -> String {
	// Convert as a UTF8 string, if possible.
	let tmp = NSData(bytes: unsafeBitCast(data.data, to: UnsafeRawPointer.self), length: Int(data.length))
	if let str = String(data: tmp as Data, encoding: String.Encoding.utf8) {
	return str
	}

	// Otherwise, return a string representation of the bytes.
	return String(describing: [UInt8](UnsafeBufferPointer(start: data.data, count: Int(data.length))))
	}

	private func stringFromUInt8Array(_ data: [UInt8]) -> String {
	// Convert as a UTF8 string, if possible.
	let tmp = NSData(bytes: data, length: data.count)
	if let str = String(data: tmp as Data, encoding: String.Encoding.utf8) {
	return str
	}

	// Otherwise, return a string representation of the bytes.
	return String(describing: data)
	}

	/// Key objects are used to identify rules that can be built.
	public struct Key: CustomStringConvertible, Equatable, Hashable {
	public let data: [UInt8]

	// MARK: CustomStringConvertible Conformance

	public var description: String {
	return "<Key: '\(toString())'>"
	}

	// MARK: Hashable Conformance

	public var hashValue: Int {
	// FIXME: Use a real hash function.
	var result = data.count
	for c in data {
	result = result*31 + Int(c)
	}
	return result
	}

	// MARK: Implementation

	public init(_ data: [UInt8]) { self.data = data }
	public init(_ str: String) { self.init(Array(str.utf8)) }

	/// Convert to a string representation.
	public func toString() -> String {
	return stringFromUInt8Array(self.data)
	}

	/// Create a Key object from an llb_data_t.
	fileprivate static func fromInternalData(_ data: llb_data_t) -> Key {
	return Key([UInt8](UnsafeBufferPointer(start: data.data, count: Int(data.length))))
	}

	/// Provide a Key contents as an llb_data_t pointer.
	fileprivate func withInternalDataPtr<T>(closure: (UnsafePointer<llb_data_t>) -> T) -> T {
	return data.withUnsafeBufferPointer { (dataPtr: UnsafeBufferPointer<UInt8>) -> T in
	var value = llb_data_t(length: UInt64(self.data.count), data: dataPtr.baseAddress)
	return withUnsafePointer(to: &value, closure)
	}
	}
	}

	public func ==(lhs: Key, rhs: Key) -> Bool {
	return lhs.data == rhs.data
	}

	/// Value objects are the result of building rules.
	public struct Value: CustomStringConvertible {
	public let data: [UInt8]

	public var description: String {
	return "<Value: '\(toString())'>"
	}

	public init(_ data: [UInt8]) { self.data = data }
	public init(_ str: String) { self.init(Array(str.utf8)) }

	/// Convert to a string representation.
	public func toString() -> String {
	return stringFromUInt8Array(self.data)
	}

	/// Create a Value object from an llb_data_t.
	fileprivate static func fromInternalData(_ data: llb_data_t) -> Value {
	return Value([UInt8](UnsafeBufferPointer(start: data.data, count: Int(data.length))))
	}

	/// Provide a Value contents as an llb_data_t pointer.
	fileprivate func withInternalDataPtr<T>(closure: (UnsafePointer<llb_data_t>) -> T) -> T {
	return data.withUnsafeBufferPointer { (dataPtr: UnsafeBufferPointer<UInt8>) -> T in
	var value = llb_data_t(length: UInt64(self.data.count), data: dataPtr.baseAddress)
	return withUnsafePointer(to: &value, closure)
	}
	}

	/// Create a Value object by providing an pointer to write the output into.
	///
	/// \param closure The closure to execute with a pointer to a llb_data_t to
	/// use. The structure must be filled in by the closure.
	///
	/// \return The output Value.
	fileprivate static func fromInternalDataOutputPtr(closure: (UnsafeMutablePointer<llb_data_t>) -> Void) -> Value {
	var data = llb_data_t()
	withUnsafeMutablePointer(to: &data, closure)
	return Value.fromInternalData(data)
	}
	}

	/// Enumeration describing the possible status of a Rule, used by \see
	/// Rule.updateStatus().
	public enum RuleStatus {
	/// Indicates the rule is being scanned.
	case IsScanning
	/// Indicates the rule is up-to-date, and doesn't need to run.
	case IsUpToDate
	/// Indicates the rule was run, and is now complete.
	case IsComplete
	}

	/// A rule represents an individual element of computation that can be performed
	/// by the build engine.
	///
	/// Each rule is identified by a unique key and the value for that key can be
	/// computed to produce a result, and supplies a set of callbacks that are used
	/// to implement the rule's behavior.
	///
	/// The computation for a rule is done by invocation of its \see Action
	/// callback, which is responsible for creating a Task object which will manage
	/// the computation.
	///
	/// All callbacks for the Rule are always invoked synchronously on the primary
	/// BuildEngine thread.
	public protocol Rule {
	/// Called to create the task to build the rule, when necessary.
	func createTask() -> Task

	/// Called to check whether the previously computed value for this rule is
	/// still valid.
	///
	/// This callback is designed for use in synchronizing values which represent
	/// state managed externally to the build engine. For example, a rule which
	/// computes something on the file system may use this to verify that the
	/// computed output has not changed since it was built.
	func isResultValid(_ priorValue: Value) -> Bool

	/// Called to indicate a change in the rule status.
	func updateStatus(_ status: RuleStatus)
	}

	/// Protocol extension for default Rule methods.
	public extension Rule {
	final func isResultValid(_ priorValue: Value) -> Bool { return true }
	final func updateStatus(_ status: RuleStatus) { }
	}

	/// A task object represents an abstract in-progress computation in the build
	/// engine.
	///
	/// The task represents not just the primary computation, but also the process
	/// of starting the computation and necessary input dependencies. Tasks are
	/// expected to be created in response to \see BuildEngine requests to initiate
	/// the production of particular result value.
	///
	/// The creator may use \see TaskBuildEngine.taskNeedsInput() to specify input
	/// dependencies on the Task. The Task itself may also specify additional input
	/// dependencies dynamically during the execution of \see Task.start() or \see
	/// Task.provideValue().
	///
	/// Once a task has been created and registered, the BuildEngine will invoke
	/// \see Task::start() to initiate the computation. The BuildEngine will provide
	/// the in progress task with its requested inputs via \see
	/// Task.provideValue().
	///
	/// After all inputs requested by the Task have been delivered, the BuildEngine
	/// will invoke \see Task.inputsAvailable() to instruct the Task it should
	/// complete its computation and provide the output. The Task is responsible for
	/// providing the engine with the computed value when ready using \see
	/// TaskBuildEngine.taskIsComplete().
	public protocol Task {
	/// Executed by the build engine when the task should be started.
	func start(_ engine: TaskBuildEngine)

	/// Invoked by the build engine to provide an input value as it becomes
	/// available.
	///
	/// \param inputID The unique identifier provided to the build engine to
	/// represent this input when requested in \see
	/// TaskBuildEngine.taskNeedsInput().
	///
	/// \param value The computed value for the given input.
	func provideValue(_ engine: TaskBuildEngine, inputID: Int, value: Value)

	/// Executed by the build engine to indicate that all inputs have been
	/// provided, and the task should begin its computation.
	///
	/// The task is expected to call \see TaskBuildEngine.taskIsComplete() when it is
	/// done with its computation.
	///
	/// It is an error for any client to request an additional input for a task
	/// after the last requested input has been provided by the build engine.
	func inputsAvailable(_ engine: TaskBuildEngine)
	}

	/// Delegate interface for use with the build engine.
	public protocol BuildEngineDelegate {
	/// Get the rule to use for the given Key.
	///
	/// The delegate must provide a rule for any possible key that can be
	/// requested (either by a client, through \see BuildEngine.build(), or via a
	/// Task through mechanisms such as \see TaskBuildEngine.taskNeedsInput(). If a
	/// requested Key cannot be supplied, the delegate should provide a dummy rule
	/// that the client can translate into an error.
	func lookupRule(_ key: Key) -> Rule
	}

	/// Wrapper to allow passing an opaque pointer to a protocol type.
	//
	// FIXME: Why do we need this, why can't we get a pointer to the protocol
	// typed object?
	private class Wrapper<T> {
	let item: T
	init(_ item: T) { self.item = item }
	}

	/// This protocol encapsulates the API that a task can use to communicate with
	/// the build engine.
	public protocol TaskBuildEngine {
	var engine: BuildEngine { get }

	/// Specify that the task depends upon the result of computing \arg key.
	///
	/// The result, when available, will be provided to the task via \see
	/// Task.provideValue(), supplying the provided \arg inputID to allow the task
	/// to identify the particular input.
	///
	/// NOTE: It is an unchecked error for a task to request the same input value
	/// multiple times.
	///
	/// \param inputID An arbitrary value that may be provided by the client to
	/// use in efficiently associating this input.
	func taskNeedsInput(_ key: Key, inputID: Int)

	/// Specify that the task must be built subsequent to the computation of \arg
	/// key.
	///
	/// The value of the computation of \arg key is not available to the task, and
	/// the only guarantee the engine provides is that if \arg key is computed
	/// during a build, then task will not be computed until after it.
	func taskMustFollow(_ key: Key)

	/// Inform the engine of an input dependency that was discovered by the task
	/// during its execution, a la compiler generated dependency files.
	///
	/// This call may only be made after a task has received all of its inputs;
	/// inputs discovered prior to that point should simply be requested as normal
	/// input dependencies.
	///
	/// Such a dependency is not used to provide additional input to the task,
	/// rather it is a way for the task to report an additional input which should
	/// be considered the next time the rule is evaluated. The expected use case
	/// for a discovered dependency is is when a processing task cannot predict
	/// all of its inputs prior to being run, but can presume that any unknown
	/// inputs already exist. In such cases, the task can go ahead and run and can
	/// report the all of the discovered inputs as it executes. Once the task is
	/// complete, these inputs will be recorded as being dependencies of the task
	/// so that it will be recomputed when any of the inputs change.
	///
	/// It is legal to call this method from any thread, but the caller is
	/// responsible for ensuring that it is never called concurrently for the same
	/// task.
	func taskDiscoveredDependency(_ key: Key)

	/// Indicate that the task has completed and provide its resulting value.
	///
	/// It is legal to call this method from any thread.
	///
	/// \param value The new value for the task's rule.
	///
	/// \param forceChange If true, treat the value as changed and trigger
	/// dependents to rebuild, even if the value itself is not different from the
	/// prior result.
	func taskIsComplete(_ result: Value, forceChange: Bool)
	}

	/// Single concrete implementation of the TaskBuildEngine protocol.
	private class TaskWrapper: CustomStringConvertible, TaskBuildEngine {
	let engine: BuildEngine
	let task: Task
	var taskInternal: OpaquePointer?

	var description: String {
	return "<TaskWrapper engine:\(engine), task:\(task)>"
	}

	init(_ engine: BuildEngine, _ task: Task) {
	self.engine = engine
	self.task = task
	}

	func taskNeedsInput(_ key: Key, inputID: Int) {
	engine.taskNeedsInput(self, key: key, inputID: inputID)
	}

	func taskMustFollow(_ key: Key) {
	engine.taskMustFollow(self, key: key)
	}

	func taskDiscoveredDependency(_ key: Key) {
	engine.taskDiscoveredDependency(self, key: key)
	}

	func taskIsComplete(_ result: Value, forceChange: Bool = false) {
	engine.taskIsComplete(self, result: result, forceChange: forceChange)
	}
	}

	/// A build engine supports fast, incremental, persistent, and parallel
	/// execution of computational graphs.
	///
	/// Computational elements in the graph are modeled by \see Rule objects, which
	/// are assocated with a specific \see Key, and which can be executed to produce
	/// an output \see Value for that key.
	///
	/// Rule objects are evaluated by first invoking their action to produce a \see
	/// Task object which is responsible for the live execution of the
	/// computation. The Task object can interact with the BuildEngine to request
	/// inputs or to notify the engine of its completion, and receives various
	/// callbacks from the engine as the computation progresses.
	///
	/// The engine itself executes using a deterministic, serial operation, but it
	/// supports parallel computation by allowing the individual Task objects to
	/// defer their own computation to signal the BuildEngine of its completion on
	/// alternate threads.
	///
	/// To support persistence, the engine allows attaching a database (\see
	/// attachDB()) which can be used to record the prior results of evaluating Rule
	/// instances.
	public class BuildEngine {
	/// The client delegate.
	private var delegate: BuildEngineDelegate

	/// The internal llbuild build engine.
	private var _engine: OpaquePointer?

	/// Our llbuild engine delegate object.
	private var _delegate = llb_buildengine_delegate_t()

	/// The number of rules which have been defined.
	public var numRules: Int = 0

	public init(delegate: BuildEngineDelegate) {
	self.delegate = delegate

	// Initialize the delegate.
	_delegate.context = unsafeBitCast(Unmanaged.passUnretained(self), to: UnsafeMutableRawPointer.self)

	_delegate.lookup_rule = { BuildEngine.toEngine($0!).lookupRule($1!, $2!) }
	// FIXME: Include cycleDetected callback.

	// Create the engine.
	_engine = llb_buildengine_create(_delegate)
	}

	deinit {
	if _engine != nil {
	close()
	}
	}

	public func close() {
	assert(_engine != nil)
	llb_buildengine_destroy(_engine)
	_engine = nil
	}

	/// Build the result for a particular key.
	public func build(key: Key) -> Value {
	return Value.fromInternalDataOutputPtr { resultPtr in
	key.withInternalDataPtr { llb_buildengine_build(self._engine, $0, resultPtr) }
	}
	}

	/// Attach a database for persisting build state.
	///
	/// A database should only be attached immediately after creating the engine,
	/// it is an error to attach a database after adding rules or initiating any
	/// builds, or to attempt to attach multiple databases.
	public func attachDB(path: String, schemaVersion: Int = 0) throws {
	let errorPtr = UnsafeMutablePointer<UnsafeMutablePointer<Int8>?>.allocate(capacity: 1)
	defer { errorPtr.deinitialize(count: 1) }

	// FIXME: Why do I have to name the closure signature here?
	var errorMsgOpt: String? = nil
	Key(path).withInternalDataPtr { (ptr) -> Void in
	if !llb_buildengine_attach_db(self._engine, ptr, UInt32(schemaVersion), errorPtr) {
	// If there was an error, report it.
	if let errorPointee = errorPtr.pointee {
	errorMsgOpt = String(cString: errorPointee)
	}
	}
	}
	// Throw the error, if found.
	if let errorMsg = errorMsgOpt {
	throw DatabaseError.AttachFailure(message: errorMsg)
	}
	}

	/// MARK: Internal Task-Only API

	fileprivate func taskNeedsInput(_ taskWrapper: TaskWrapper, key: Key, inputID: Int) {
	key.withInternalDataPtr { keyPtr in
	llb_buildengine_task_needs_input(self._engine, taskWrapper.taskInternal, keyPtr, UInt(inputID))
	}
	}

	fileprivate func taskMustFollow(_ taskWrapper: TaskWrapper, key: Key) {
	key.withInternalDataPtr { keyPtr in
	llb_buildengine_task_must_follow(self._engine, taskWrapper.taskInternal, keyPtr)
	}
	}

	fileprivate func taskDiscoveredDependency(_ taskWrapper: TaskWrapper, key: Key) {
	key.withInternalDataPtr { keyPtr in
	llb_buildengine_task_discovered_dependency(self._engine, taskWrapper.taskInternal, keyPtr)
	}
	}

	fileprivate func taskIsComplete(_ taskWrapper: TaskWrapper, result: Value, forceChange: Bool = false) {
	result.withInternalDataPtr { dataPtr in
	llb_buildengine_task_is_complete(self._engine, taskWrapper.taskInternal, dataPtr, forceChange)
	}
	}

	/// MARK: Internal Delegate Implementation

	/// Helper function for getting the engine from the delegate context.
	static fileprivate func toEngine(_ context: UnsafeMutableRawPointer) -> BuildEngine {
	return Unmanaged<BuildEngine>.fromOpaque(context).takeUnretainedValue()
	}

	/// Helper function for getting the rule from a rule delegate context.
	static fileprivate func toRule(_ context: UnsafeMutableRawPointer) -> Rule {
	return Unmanaged<Wrapper<Rule>>.fromOpaque(context).takeUnretainedValue().item
	}

	/// Helper function for getting the task from a task delegate context.
	static fileprivate func toTaskWrapper(_ context: UnsafeMutableRawPointer) -> TaskWrapper {
	return Unmanaged<TaskWrapper>.fromOpaque(context).takeUnretainedValue()
	}

	fileprivate func lookupRule(_ key: UnsafePointer<llb_data_t>, _ ruleOut: UnsafeMutablePointer<llb_rule_t>) {
	numRules += 1

	// Get the rule from the client.
	let rule = delegate.lookupRule(Key.fromInternalData(key.pointee))

	// Fill in the output structure.
	//
	// FIXME: We need a deallocation callback in order to ensure this is released.
	ruleOut.pointee.context = unsafeBitCast(Unmanaged.passRetained(Wrapper(rule)), to: UnsafeMutableRawPointer.self)
	ruleOut.pointee.create_task = { (context, engineContext) -> OpaquePointer! in
	let rule = BuildEngine.toRule(context!)
	let engine = BuildEngine.toEngine(engineContext!)
	return engine.ruleCreateTask(rule)
	}
	ruleOut.pointee.is_result_valid = { (context, engineContext, internalRule, value) -> Bool in
	let rule = BuildEngine.toRule(context!)
	return rule.isResultValid(Value.fromInternalData(value!.pointee))
	}
	ruleOut.pointee.update_status = { (context, engineContext, status) in
	let rule = BuildEngine.toRule(context!)
	let status = { (kind: llb_rule_status_kind_t) -> RuleStatus in
	switch kind.rawValue {
	case llb_rule_is_scanning.rawValue: return .IsScanning
	case llb_rule_is_up_to_date.rawValue: return .IsUpToDate
	case llb_rule_is_complete.rawValue: return .IsComplete
	default:
	fatalError("unknown status kind")
	} }(status)
	return rule.updateStatus(status)
	}
	}

	private func ruleCreateTask(_ rule: Rule) -> OpaquePointer {
	// Create the task.
	let task = rule.createTask()

	// Create the task wrapper.
	//
	// Note that the wrapper here is serving two purposes, it is providing a way
	// to communicate the internal task object to clients, and it is providing a
	// way to segregate the Task-only API from the rest of the BuildEngine API.
	let taskWrapper = TaskWrapper(self, task)

	// Create the task delegate.
	//
	// FIXME: Separate the delegate from the context pointer.
	var taskDelegate = llb_task_delegate_t()
	// FIXME: We need a deallocation callback in order to ensure this is released.
	taskDelegate.context = unsafeBitCast(Unmanaged.passRetained(taskWrapper), to: UnsafeMutableRawPointer.self)
	taskDelegate.start = { (context, engineContext, internalTask) in
	let taskWrapper = BuildEngine.toTaskWrapper(context!)
	taskWrapper.task.start(taskWrapper)
	}
	taskDelegate.provide_value = { (context, engineContext, internalTask, inputID, value) in
	let taskWrapper = BuildEngine.toTaskWrapper(context!)
	taskWrapper.task.provideValue(taskWrapper, inputID: Int(inputID), value: Value.fromInternalData(value!.pointee))
	}
	taskDelegate.inputs_available = { (context, engineContext, internalTask) in
	let taskWrapper = BuildEngine.toTaskWrapper(context!)
	taskWrapper.task.inputsAvailable(taskWrapper)
	}

	// Create the internal task.
	taskWrapper.taskInternal = llb_task_create(taskDelegate)

	// FIXME: Why do we have both of these, it is kind of annoying. It makes
	// some amount of sense in the C++ API, but the C API should probably just
	// collapse them.
	return llb_buildengine_register_task(self._engine, taskWrapper.taskInternal)
	}
	}