Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Leif/documentation #16

Merged
merged 13 commits into from
Aug 9, 2024
Merged

Leif/documentation #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
656961f
Update README.md
0xLeif Aug 8, 2024
584be12
Create installation.md
0xLeif Aug 8, 2024
11665d3
Update README.md
0xLeif Aug 8, 2024
deba572
Create usage-overview.md
0xLeif Aug 8, 2024
7be6c02
Update README.md
0xLeif Aug 8, 2024
c80fc54
Create usage-sendablevalue.md
0xLeif Aug 8, 2024
d38b8fd
Create usage-future.md
0xLeif Aug 8, 2024
df25340
Create usage-deferred.md
0xLeif Aug 8, 2024
c8bb2a8
Create usage-stream.md
0xLeif Aug 9, 2024
e7ce9a3
Update usage-sendablevalue.md
0xLeif Aug 9, 2024
6da9f5f
Create usage-publisher.md
0xLeif Aug 9, 2024
2802192
Create usage-schedule-task.md
0xLeif Aug 9, 2024
c6dacfe
Create contributing.md
0xLeif Aug 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
249 changes: 26 additions & 223 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,236 +1,39 @@
# Later

`Later` is a lightweight Swift 6 library designed to simplify asynchronous programming by providing foundational building blocks such as `SendableValue`, `Future`, `Deferred`, `Stream`, and `Publisher`. These components enable you to manage and coordinate asynchronous tasks, making it easier to write clean and maintainable code.
**Later** is a Swift 6 library that simplifies asynchronous programming by offering simple building blocks for managing concurrency. **Later** helps you write clean, maintainable code that efficiently handles complex asynchronous tasks.

## Features
## Key Features

- **SendableValue**: A generic [`Sendable`](https://developer.apple.com/documentation/swift/sendable) value that uses [`OSAllocatedUnfairLock`](https://developer.apple.com/documentation/os/osallocatedunfairlock).
- **Future**: Represents a value that will be available asynchronously in the future.
- **Deferred**: Represents a value that will be computed and available asynchronously when explicitly started.
- **Stream**: Represents an asynchronous sequence of values emitted over time.
- **Publisher**: Allows objects to subscribe to changes in state or data and notifies subscribers when the state or data changes.
- **Subscribing**: A protocol for objects that want to observe changes in state or data.
**Later** offers a range of tools to make asynchronous programming more straightforward and efficient:

## Installation
- **SendableValue**: A generic [`Sendable`](https://developer.apple.com/documentation/swift/sendable) value that ensures thread safety using [`OSAllocatedUnfairLock`](https://developer.apple.com/documentation/os/osallocatedunfairlock).
- **Future**: Represents a value that will be available asynchronously in the future, enabling you to handle tasks that take time to complete.
- **Deferred**: Represents a value that will be computed and available asynchronously when explicitly started, giving you control over when a task begins.
- **Stream**: Represents an asynchronous sequence of values emitted over time, perfect for handling data that updates periodically.
- **Publisher**: Allows objects to subscribe to changes in state or data, notifying subscribers when updates occur, ensuring your application responds dynamically to changes.
- **Subscribing**: A protocol for objects that want to observe changes in state or data, making it easy to react to updates.

### Swift Package Manager
## Getting Started

Add `Later` to your `Package.swift` file:
To start using **Later**, follow our [Installation Guide](documentation/installation.md) which provides step-by-step instructions for adding **Later** to your Swift project using Swift Package Manager.

```swift
dependencies: [
.package(url: "https://github.com/0xLeif/Later.git", from: "1.0.0")
]
```
After installation, explore our [Usage Overview](documentation/usage-overview.md) to see how to implement each of the key features in your own code. From simple examples to more in-depth explorations, these guides will help you integrate **Later** into your asynchronous workflows effectively.

And add it to your target’s dependencies:
## Documentation

```swift
.target(
name: "YourTarget",
dependencies: ["Later"]
)
```
Here’s a breakdown of the **Later** documentation:

## Usage
- [Installation Guide](documentation/installation.md): Instructions on how to install **Later** using Swift Package Manager.
- [Usage Overview](documentation/usage-overview.md): An overview of **Later**'s key features with example implementations.
- Detailed Usage Guides:
- [SendableValue Usage](documentation/usage-sendablevalue.md)
- [Future Usage](documentation/usage-future.md)
- [Deferred Usage](documentation/usage-deferred.md)
- [Stream Usage](documentation/usage-stream.md)
- [Publisher and Subscribing Usage](documentation/usage-publisher.md)
- [Schedule Task Usage](documentation/usage-schedule-task.md)
- [Contributing](documentation/contributing.md): Information on how to contribute to the **Later** project.

### SendableValue
## Next Steps

SendableValue is a thread-safe value-type wrapper for a value that can be safely shared across concurrent tasks. It allows you to set and retrieve the value asynchronously.

```swift
let sendableValue = SendableValue<Int>(42)
sendableValue.set(value: 100)
let value = await sendableValue.value
#expect(value == 100)
```

This ensures that the value is safely managed across different contexts, providing a simple way to handle mutable state in concurrent programming.

### Future

A `Future` represents a value that will be available asynchronously in the future.

```swift
import Later

@Sendable func asyncTask() async throws -> String {
return "Hello"
}

let future = Future {
do {
let result = try await asyncTask()
return result
} catch {
throw error
}
}

do {
let result = try await future.value
print(result) // Prints "Hello"
} catch {
print("Error: \(error)")
}
```

### Deferred

A `Deferred` represents a value that will be computed and available asynchronously when explicitly started.

```swift
import Later

@Sendable func asyncDeferredTask() async throws -> String {
return "Deferred Hello"
}

var deferred = Deferred {
do {
let result = try await asyncDeferredTask()
return result
} catch {
throw error
}
}

deferred.start()

do {
let result = try await deferred.value
print(result) // Prints "Deferred Hello"
} catch {
print("Error: \(error)")
}
```

### Stream

A `Stream` represents an asynchronous sequence of values emitted over time.

```swift
import Later

@Sendable func asyncStreamTask1() async throws -> String {
return "First value"
}

@Sendable func asyncStreamTask2() async throws -> String {
return "Second value"
}

let stream = Stream<String> { emitter in
do {
let value1 = try await asyncStreamTask1()
emitter.emit(value: value1)
let value2 = try await asyncStreamTask2()
emitter.emit(value: value2)
} catch {
// Handle error if necessary
}
}

Task {
for try await value in stream {
print(value) // Prints "First value" and then "Second value"
}
}
```

### Publisher and Subscribing

A `Publisher` allows objects to subscribe to changes in data and notifies subscribers when the data changes.

```swift
import Later

class MySubscriber: Subscribing {
typealias Value = String

func didUpdate(newValue: String?) {
print("New value: \(String(describing: newValue))")
}
}

let subscriber = MySubscriber()
let publisher = Publisher(initialValue: "Initial value", subscribers: [subscriber])

// Using Future with Publisher
let future = await publisher.future(
didSucceed: nil,
didFail: nil,
task: {
return "Future value"
}
)

do {
let value = try await future.value
print("Future completed with value: \(value)")
} catch {
print("Future failed with error: \(error)")
}

// Using Deferred with Publisher
var deferred = await publisher.deferred(
didSucceed: nil,
didFail: nil,
task: {
return "Deferred value"
}
)

deferred.start()

do {
let value = try await deferred.value
print("Deferred completed with value: \(value)")
} catch {
print("Deferred failed with error: \(error)")
}

// Using Stream with Publisher
let stream = await publisher.stream(
didSucceed: nil,
didFail: nil,
task: { emitter in
emitter.emit(value: "Stream value 1")
emitter.emit(value: "Stream value 2")
}
)

var streamValues: [String] = []
for try await value in stream {
streamValues.append(value)
print("Stream emitted value: \(value)")
}

print("Stream completed with values: \(streamValues)")
```

### Schedule Task

You can schedule tasks to be executed after a specified duration using the `Task` extension.

Availability: `@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)`

```swift
import Later

func asyncScheduledTask() async throws {
print("Task executed")
}

do {
try await Task.schedule(for: .seconds(5)) {
try await asyncScheduledTask()
}
} catch {
print("Failed to execute task: \(error)")
}
```

## Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or bug reports. Please create an issue before submitting any pull request to make sure the work isn’t already being worked on by someone else.
To continue, head over to our [Installation Guide](documentation/installation.md) and get **Later** set up in your project. After installation, you can dive into the [Usage Overview](documentation/usage-overview.md) to see how to start leveraging the power of asynchronous programming with **Later**.
60 changes: 60 additions & 0 deletions documentation/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Contributing to Later

Thank you for considering contributing to **Later**! Your contributions help make this project better for everyone.

## How to Contribute

### 1. Reporting Bugs

If you encounter any bugs, please open an issue on GitHub. When reporting a bug, please include:

- A clear and descriptive title.
- A detailed description of the bug, including steps to reproduce it.
- The expected behavior and what actually happened.
- The version of **Later** you are using.
- Any relevant screenshots or logs.

### 2. Suggesting Features

We welcome new ideas! If you have a feature you'd like to see added to **Later**, please open an issue and describe:

- The problem the feature would solve.
- How you think the feature should work.
- Any additional context or examples that would help illustrate your idea.

### 3. Submitting Pull Requests

If you'd like to contribute code to **Later**, follow these steps:

1. **Fork the Repository**: Create a personal fork of the **Later** repository on GitHub.
2. **Clone Your Fork**: Clone your fork to your local machine:
```bash
git clone https://github.com/your-username/Later.git
```
3. **Create a New Branch**: Create a new branch for your feature or bugfix:
```bash
git checkout -b my-feature-branch
```
4. **Make Changes**: Implement your changes in the new branch.
5. **Test Your Changes**: Ensure your changes pass all tests. Add new tests if necessary.
6. **Commit Your Changes**: Commit your changes with a descriptive commit message:
```bash
git commit -m "Add my new feature"
```
7. **Push to GitHub**: Push your branch to your GitHub fork:
```bash
git push origin my-feature-branch
```
8. **Create a Pull Request**: Go to the **Later** repository on GitHub and create a pull request from your branch.

### 4. Code Style

Please follow the coding style guidelines used in the **Later** project. Consistent code style helps make the codebase more maintainable and easier to review.

### 5. License

By contributing to **Later**, you agree that your contributions will be licensed under the same license as the project: [MIT License]([LICENSE](https://github.com/0xLeif/Later/blob/main/LICENSE)).

## Thank You!

Your contributions are highly valued and appreciated. Thank you for helping improve **Later**!
Loading
Loading