QueueSafeValue

Framework that provides thread-safe (queue-safe) access to the value.

Advantages

Embedded DispatchSemaphore

Just use specific access functions (commands) of a QueueSafeValue and don't think about thread synchronization.
Built-in scheduler

Scheduler organises synchronous and asynchronous commands executing.
Embedded Comand Queue (Priority queue)

Command Queue needed to organize the sequence of commands. All commands will be executed in order of priority, one after the other.
Priority command execution

Ability to prioritize updates or access to QueueSafeValue. This means that some commands will run faster than others.
Doesn't increment object reference count
Always returns a result and avoids returning optionals

always returns Result<Value, QueueSafeValueError>
Available different value manipulation commands

atomic command: queueSafeValue.wait.lowestPriority.get()

value processing command in a closure: queueSafeValue.wait.lowestPriority.get { result in ... }

value accessing command in a closure: queueSafeValue.wait.lowestPriority.set { currentValue in currentVaule = newValue }

Documentation

Base structure of command

queueSafeValue.{schedule}.{priority}.{command}

Definitions:

🇨🇴🇲🇲🇦🇳🇩 🇶🇺🇪🇺🇪

stores commands and executes them sequentially with the correct priority
QueueSafeValue has a built-in command queue (priority queue) where all closures (commands) will be placed and perfomed after

🇨🇱🇴🇸🇺🇷🇪🇸

is a closure inside which the value is accessed
protected from concurrent access to value (works as critical section, implementation based on DispatchGroup)

Available command closures:

commandClosure - provides access to the value
accessClosure - provides direct access to the value (using inout keyword)
commandCompletionClosure - a closure that must always be performed (called) if available as a property inside the commandClosure or accessClosure. Executing the closure notifies the command queue that the command has completed. After that, the command queue will unblock the access to the value and execute the next command, if it exists.

Execution method:

completion commandClosure/accessClosure - closure that expects to work with serial code within itself.
manualCompletion commandClosure/accessClosure - closure that expects to work with serial / asynchronous code within itself. This closure must be completed manually by calling the CommandCompletionClosure, placed as a property inside commandClosure or accessClosure

Request components:

🇸🇨🇭🇪🇩🇺🇱🇪

Available schedules:

wait - (sync) performs commands sequentially. Blocks the queue where this code runs until it completed
async - performs a command asynchronously of the queue that calls this function

🇵🇷🇮🇴🇷🇮🇹🇾

Available priorities:

lowestPriority - a command with lowest priority will be executed last
highestPriority - a command with highest priority will be executed first

🇨🇴🇲🇲🇦🇳🇩

Available synchronous commands:

1. `get` value synchronously

returns CurrentValue or QueueSafeValueError
is used when only the return value is required (no value processing)

func get() -> Result<CurrentValue, QueueSafeValueError>

// Option 1
let queueSafeValue = QueueSafeValue(value: true)
DispatchQueue.global(qos: .utility).async {
    let result = queueSafeValue.wait.lowestPriority.get()
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2
let queueSafeSyncedValue = QueueSafeSyncedValue(value: "a")
DispatchQueue.global(qos: .utility).async {
    let result = queueSafeSyncedValue.lowestPriority.get()
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

2. `get` value synchronously inside the `commandClosure`

returns CurrentValue or QueueSafeValueError inside commandClosure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the commandClosure
commandClosure will be completed automatically

func get(completion commandClosure: ((Result<CurrentValue, QueueSafeValueError>) -> Void)?)

// Option 1
let queueSafeValue = QueueSafeValue(value: 6)
DispatchQueue.global(qos: .unspecified).async {
    queueSafeValue.wait.lowestPriority.get { result in
        switch result {
        case .failure(let error): print(error)
        case .success(let value): print(value)
        }
    }
}

// Option 2
let queueSafeSyncedValue = QueueSafeSyncedValue(value: [1,2,3])
DispatchQueue.global(qos: .utility).async {
    queueSafeSyncedValue.lowestPriority.get { result in
        switch result {
        case .failure(let error): print(error)
        case .success(let value): print(value)
        }
    }
}

3. `get` value synchronously inside the `commandClosure` with manual completion

returns CurrentValue or QueueSafeValueError and CommandCompletionClosure inside the commandClosure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the commandClosure
important: commandClosure must be completed manually by performing (calling) CommandCompletionClosure

func get(manualCompletion commandClosure: ((Result<CurrentValue, QueueSafeValueError>,
                                            @escaping CommandCompletionClosure) -> Void)?)

// Option 1
let queueSafeValue = QueueSafeValue(value: 4.44)
DispatchQueue.global(qos: .unspecified).async {
    queueSafeValue.wait.highestPriority.get { result, done in
        switch result {
        case .failure(let error): print(error)
        case .success(let value): print(value)
        }
        done() // Must always be executed (called). Can be called in another DispatchQueue.
    }
}

// Option 2
let queueSafeSyncedValue = QueueSafeSyncedValue(value: 4.45)
DispatchQueue.global(qos: .utility).async {
    queueSafeSyncedValue.highestPriority.get { result, done in
        switch result {
        case .failure(let error): print(error)
        case .success(let value): print(value)
        }
        done() // Must always be executed (called). Can be called in another DispatchQueue.
    }
}

4. `set` value synchronously

returns UpdatedValue or QueueSafeValueError
is used when only the set of value is required (no value processing)

@discardableResult
func set(newValue: Value) -> Result<UpdatedValue, QueueSafeValueError>

// Option 1
let queueSafeValue = QueueSafeValue<Int>(value: 1)
DispatchQueue.global(qos: .userInitiated).async {
    let result = queueSafeValue.wait.lowestPriority.set(newValue: 2)
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2
let queueSafeSyncedValue = QueueSafeSyncedValue(value: "b")
DispatchQueue.global(qos: .userInitiated).async {
    let result = queueSafeSyncedValue.lowestPriority.set(newValue: "b1")
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

5. `set` value synchronously inside the `accessClosure`

sets CurrentValue inside the accessClosure
is used when it is necessary to both read and write a value inside one closure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the accessClosure
Attention: accessClosure will not be run if any QueueSafeValueError occurs

@discardableResult
func set(completion accessClosure: ((inout CurrentValue) -> Void)?) -> Result<UpdatedValue, QueueSafeValueError>

// Option 1
let queueSafeValue = QueueSafeValue(value: 1)
DispatchQueue.main.async {
    let result = queueSafeValue.wait.lowestPriority.set { $0 = 3 }
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2
let queueSafeSyncedValue = QueueSafeSyncedValue(value: ["a":1])
DispatchQueue.main.async {
    let result = queueSafeSyncedValue.lowestPriority.set { $0["b"] = 2 }
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

6. `set` value synchronously inside the `accessClosure` with manual completion

sets CurrentValue inside the accessClosure
is used when it is necessary to both read and write a value inside one closure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the accessClosure
important: accessClosure must be completed manually by performing (calling) CommandCompletionClosure
Attention: accessClosure will not be run if any QueueSafeValueError occurs.

@discardableResult
func set(manualCompletion accessClosure: ((inout CurrentValue, 
                                           @escaping CommandCompletionClosure) -> Void)?) -> Result<UpdatedValue, QueueSafeValueError>

// Option 1
let queueSafeValue = QueueSafeValue(value: "value 1")
DispatchQueue.main.async {
    let result = queueSafeValue.wait.lowestPriority.set { currentValue, done in
        currentValue = "value 2"
        done() // Must always be executed (called). Can be called in another DispatchQueue.
    }
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2
let queueSafeSyncedValue = QueueSafeSyncedValue(value: "value a")
DispatchQueue.main.async {
    let result = queueSafeSyncedValue.lowestPriority.set { currentValue, done in
        currentValue = "value b"
        done() // Must always be executed (called). Can be called in another DispatchQueue.
    }
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

7. `map` value synchronously inside the `commandClosure`

maps (transforms) CurrentValue to MappedValue inside the commandClosure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the commandClosure

func map<MappedValue>(completion commandClosure: ((CurrentValue) -> MappedValue)?) -> Result<MappedValue, QueueSafeValueError>

// Option 1
let queueSafeValue = QueueSafeValue(value: 5)
DispatchQueue.global(qos: .background).async {
    let result = queueSafeValue.wait.lowestPriority.map { "\($0)" }
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2
let queueSafeSyncedValue = QueueSafeSyncedValue(value: "1")
DispatchQueue.global(qos: .background).async {
    let result = queueSafeSyncedValue.lowestPriority.map { Int($0) }
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(String(describing: value))
    }
}

Available asynchronous commands:

1. `get` value ssynchronously inside `commandClosure`

returns CurrentValue or QueueSafeValueError inside the commandClosure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the commandClosure
commandClosure will be completed automatically

func get(completion commandClosure: ((Result<CurrentValue, QueueSafeValueError>) -> Void)?)

// Option 1
let queueSafeValue = QueueSafeValue(value: true)
queueSafeValue.async(performIn: .global(qos: .utility)).highestPriority.get { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2
let queueSafeAsyncedValue = QueueSafeAsyncedValue(value: true, queue: .global(qos: .utility))
queueSafeAsyncedValue.highestPriority.get { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

2. `get` value ssynchronously inside the `commandClosure` with manual completion

returns CurrentValue or QueueSafeValueError and CommandCompletionClosure inside the commandClosure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the commandClosure
important: commandClosure must be completed manually by performing (calling) CommandCompletionClosure

func get(manualCompletion commandClosure: ((Result<CurrentValue, QueueSafeValueError>,
                                            @escaping CommandCompletionClosure) -> Void)?)

// Option 1
let queueSafeValue = QueueSafeValue(value: "test")
queueSafeValue.async(performIn: .global(qos: .utility)).highestPriority.get { result, done in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
    done() // Must always be executed (called). Can be called in another DispatchQueue.
}

// Option 2
let queueSafeAsyncedValue = QueueSafeAsyncedValue(value: "super test", queue: .global(qos: .background))
queueSafeAsyncedValue.highestPriority.get { result, done in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
    done() // Must always be executed (called). Can be called in another DispatchQueue.
}

3. `set` value ssynchronously

returns UpdatedValue or QueueSafeValueError inside the commandClosure
is used when only the set of value is required (no value processing)

func set(newValue: Value, completion commandClosure: ((Result<UpdatedValue, QueueSafeValueError>) -> Void)? = nil)

// Option 1
let queueSafeValue = QueueSafeValue(value: 7)

// Without completion block
queueSafeValue.async(performIn: .main).highestPriority.set(newValue: 8)

// With completion block
queueSafeValue.async(performIn: .main).highestPriority.set(newValue: 9) { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2
let queueSafeAsyncedValue = QueueSafeAsyncedValue(value: 7, queue: .global())

// Without completion block
queueSafeAsyncedValue.highestPriority.set(newValue: 8)

// With completion block
queueSafeAsyncedValue.highestPriority.set(newValue: 9) { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

4. `set` value ssynchronously inside the `accessClosure`

sets CurrentValue inside the accessClosure
is used when it is necessary to both read and write a value inside one closure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the accessClosure
Attention: accessClosure will not be run if any QueueSafeValueError occurs

func set(accessClosure: ((inout CurrentValue) -> Void)?,
         completion commandClosure: ((Result<UpdatedValue, QueueSafeValueError>) -> Void)? = nil)

// Option 1.
let queueSafeValue = QueueSafeValue(value: 1)

// Without completion block
queueSafeValue.async(performIn: .background).highestPriority.set { $0 = 10 }

// With completion block
queueSafeValue.async(performIn: .background).highestPriority.set { currentValue in
    currentValue = 11
} completion: { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2.
let queueSafeAsyncedValue = QueueSafeAsyncedValue(value: 1, queue: .global(qos: .userInteractive))

// Without completion block
queueSafeAsyncedValue.highestPriority.set { $0 = 10 }

// With completion block
queueSafeAsyncedValue.highestPriority.set { currentValue in
    currentValue = 11
} completion: { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

5. `set` value ssynchronously inside the `accessClosure` with manual completion

sets CurrentValue inside the accessClosure
is used when it is necessary to both read and write a value inside one closure
is used as a critical section when it is necessary to hold reading / writing of the value while it is processed in the accessClosure
important: accessClosure must be completed manually by performing (calling) CommandCompletionClosure
Attention: accessClosure will not be run if any QueueSafeValueError occurs.

func set(manualCompletion accessClosure: ((inout CurrentValue, @escaping CommandCompletionClosure) -> Void)?,
         completion commandClosure: ((Result<UpdatedValue, QueueSafeValueError>) -> Void)? = nil)

// Option 1.
let queueSafeValue = QueueSafeValue(value: 999.1)

// Without completion block
queueSafeValue.async(performIn: .background).highestPriority.set { currentValue, done in
    currentValue = 999.2
    done() // Must always be executed (called). Can be called in another DispatchQueue.
}

// With completion block
queueSafeValue.async(performIn: .background).highestPriority.set { currentValue, done in
    currentValue = 999.3
    done() // Must always be executed (called). Can be called in another DispatchQueue.
} completion: { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

// Option 2.
let queueSafeAsyncedValue = QueueSafeAsyncedValue(value: 1000.1, queue: .global(qos: .userInteractive))

// Without completion block
queueSafeAsyncedValue.highestPriority.set { currentValue, done in
    currentValue = 1000.2
    done() // Must always be executed (called). Can be called in another DispatchQueue.
}

// With completion block
queueSafeAsyncedValue.highestPriority.set { currentValue, done in
    currentValue = 1000.3
    done() // Must always be executed (called). Can be called in another DispatchQueue.
} completion: { result in
    switch result {
    case .failure(let error): print(error)
    case .success(let value): print(value)
    }
}

Requirements

iOS 8.0+
Xcode 10+
Swift 5.1+

Installation

Step 1:

QueueSafeValue is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'QueueSafeValue'

Step 2:

run pod install in your project root folder

Step 3:

To use the installed QueueSafeValue framework, simply import the QueueSafeValue in the swift file in which you are going to apply it.

Author

Vasily Bodnarchuk, https://www.linkedin.com/in/vasily-bodnarchuk/

License

QueueSafeValue is available under the MIT license. See the LICENSE file for more info.

QueueSafeValue 0.8

QueueSafeValue 0.8

QueueSafeValue 0.8

QueueSafeValue

Advantages

Embedded DispatchSemaphore

Built-in scheduler

Embedded Comand Queue (Priority queue)

Priority command execution

Doesn't increment object reference count

Always returns a result and avoids returning optionals

Available different value manipulation commands

Documentation

Base structure of command

Definitions:

🇨​​​​​🇴​​​​​🇲​​​​​🇲​​​​​🇦​​​​​🇳​​​​​🇩 🇶​​​​​🇺​​​​​🇪​​​​​🇺​​​​​🇪​​​​​

🇨​​​​​🇱​​​​​🇴​​​​​🇸​​​​​🇺​​​​​🇷​​​​​🇪​​​​​​​​​🇸​

Request components:

🇸​​​​​🇨​​​​​🇭​​​​​🇪​​​​​🇩​​​​​🇺​​​​​🇱​​​​​🇪​​​​​

🇵​​​​​🇷​​​​​🇮​​​​​🇴​​​​​🇷​​​​​🇮​​​​​🇹​​​​​🇾​​​​​

🇨​​​​​🇴​​​​​🇲​​​​​🇲​​​​​🇦​​​​​🇳​​​​​🇩​​​​​

Available synchronous commands:

1. get value synchronously

2. get value synchronously inside the commandClosure

3. get value synchronously inside the commandClosure with manual completion

4. set value synchronously

5. set value synchronously inside the accessClosure

6. set value synchronously inside the accessClosure with manual completion

7. map value synchronously inside the commandClosure

Available asynchronous commands:

1. get value ssynchronously inside commandClosure

2. get value ssynchronously inside the commandClosure with manual completion

3. set value ssynchronously

4. set value ssynchronously inside the accessClosure

5. set value ssynchronously inside the accessClosure with manual completion

Requirements

Installation

Step 1:

Step 2:

Step 3:

Author

License

Embedded `DispatchSemaphore`

Built-in `scheduler`

Embedded `Comand Queue` (`Priority queue`)

Priority `command` execution

🇨🇴🇲🇲🇦🇳🇩 🇶🇺🇪🇺🇪

🇨🇱🇴🇸🇺🇷🇪🇸

🇸🇨🇭🇪🇩🇺🇱🇪

🇵🇷🇮🇴🇷🇮🇹🇾

🇨🇴🇲🇲🇦🇳🇩

1. `get` value synchronously

2. `get` value synchronously inside the `commandClosure`

3. `get` value synchronously inside the `commandClosure` with manual completion

4. `set` value synchronously

5. `set` value synchronously inside the `accessClosure`

6. `set` value synchronously inside the `accessClosure` with manual completion

7. `map` value synchronously inside the `commandClosure`

1. `get` value ssynchronously inside `commandClosure`

2. `get` value ssynchronously inside the `commandClosure` with manual completion

3. `set` value ssynchronously

4. `set` value ssynchronously inside the `accessClosure`

5. `set` value ssynchronously inside the `accessClosure` with manual completion