Caffeination

public class Caffeination

An instance of a sleep-prevention session.

Show on GitHub
  • Opt

    A customization option for a Caffeination.

    Note

    Any given Caffeination can be passed only one of each Opt. So, for instance, it is valid to pass a .timed and .process Opt; however, it is not possible to have two different .process Opts.
    See more

    Declaration

    Swift

    public enum Opt
    Show on GitHub

  • The expected location of the caffeinate executable.

    Declaration

    Swift

    public static let caffeinatePath: URL
    Show on GitHub

  • Indicates whether the caffeinate executable is in the correct location.

    Declaration

    Swift

    public static var caffeinateExists: Bool { get }
    Show on GitHub

  • If true, will automatically set the caffeinate process to terminate with this application’s termination (when the .process option is not passed). Has no bearing on traps.

    Declaration

    Swift

    public var limitLifetime: Bool
    Show on GitHub

  • The function to be executed once the Caffeination terminates.

    Declaration

    Swift

    public var terminationHandler: ((Caffeination) -> Void)?
    Show on GitHub

  • The options for the Caffeination.

    Declaration

    Swift

    public var opts: [Opt] { get set }
    Show on GitHub

  • Whether a Caffeination is currently ongoing.

    Declaration

    Swift

    public var isActive: Bool { get }
    Show on GitHub

  • Whether the Caffeination will be automatically terminated when the app is quit using the “Quit” menu or receives a termination signal. Setting this property will enable or disable this safety mechanism. Not to be confused

    Declaration

    Swift

    public var interceptAppTermination: Bool { get set }
    Show on GitHub

  • Initializes a new Caffeination.

    Declaration

    Swift

    public init(withOpts opts: [Opt] = Opt.defaults, safety: Bool = true, terminationHandler: ((Caffeination) -> Void)? = nil)

    Parameters

    opts

    The options with which to start the Caffeintaion.
    safety

    Whether to enable safety measures to ensure that no “zombie” caffeinate processes can outlive the current application. Set to true by default, which is recommended.
    terminationHandler

    A handler that will be called when the Caffeination stops. Will be set to nil if the parameter is not specified.
    Show on GitHub

  • Generates a closure that Caffeinates for the duration of its execution. Inherits the Caffeination object’s opts, of which only .disk, .display, .idle, and .user will be honored.

    Throws

    CaffeinationError.alreadyActive if a Caffeination is already active.

    Declaration

    Swift

    public func closure<Param, Ret>(_ sourceClosure: @escaping (_ parameter: Param) -> Ret) throws -> (Param) -> Ret

    Parameters

    sourceClosure

    The closure during which to Caffeinate.
    parameter

    A parameter of any type.

    Return Value

    A closure that will create an active Caffeination for the duration of its synchronous execution.

    Show on GitHub

  • Generates a Caffienated closure that prioritizes execution of the closure above Caffeination. Thus, a closure will be returned and be allowed to run even if caffeinate cannot be started. Failures to start caffeinate will occur silently; manually use Caffeination.caffeinateExists to check that the intended behavior will occur.

    Declaration

    Swift

    public func silentClosure<Param, Ret>(_ sourceClosure: @escaping (_ parameter: Param) -> Ret) -> (Param) -> Ret

    Parameters

    sourceClosure

    The closure for the duration of which the Caffeination will be active.

    Return Value

    A closure that will create an active Caffeination for the duration of its synchronous execution.

    Show on GitHub

  • Starts preventing sleep (i.e., the Caffeination).

    Throws

    CaffeinationError.alreadyActive if a Caffeination is already active, CaffeinationError.caffeinateNotFound if the user does not have the caffeinate binary at the expected location, or any error generated by Process.run() on macOS 10.13 or higher.

    Warning

    This method could theoretically raise an NSInvalidArgumentException if run under exceptional conditions on macOS < 10.13. While every attempt is made to eliminate potential causes of an NSInvalidArgumentException, it is still possible that such an exception—which cannot be caught in Swift—could be raised.

    Declaration

    Swift

    public func start() throws
    Show on GitHub

  • Starts preventing sleep (i.e., the Caffeination) with the specified options, overriding any that may have previously been set.

    Throws

    CaffeinationError.alreadyActive if a Caffeination is already active, CaffeinationError.caffeinateNotFound if the user does not have the caffeinate binary at the expected location, or any error generated by Process.run() on macOS 10.13 or higher.

    Warning

    This method could theoretically raise an NSInvalidArgumentException if run under exceptional conditions on macOS < 10.13. While every attempt is made to eliminate potential causes of an NSInvalidArgumentException, it is still possible that such an exception—which cannot be caught in Swift—could be raised.

    Declaration

    Swift

    public func start(withOpts opts: [Opt]) throws

    Parameters

    opts

    The options with which to start the Caffeination (overrides the existing value of self.opts).
    Show on GitHub

  • Stops the Caffeination if it is active.

    Declaration

    Swift

    public func stop()
    Show on GitHub

  • Sets the verbosity level of logging.

    Declaration

    Swift

    public static func setLogLevel(_ level: LogLevel)

    Parameters

    level

    A LogLevel specifying the types of logs to receive. Levels are cumulative (i.e., setting the log level to .info will also print warnings and errors). Pass .none to disable logging.
    Show on GitHub