update: docs + usage featuring latest improvements

[incertum]

update: docs featuring latest improvements

#135 should land first as I reference those updates.

CC @ktoso @heckj

[incertum]

Quick note: Some of the Documentation failures are due to the fact that I need to rebase this once #135 is merged. However, I already saw some suggestions re layout or heading levels, @heckj happy to follow your suggestions!

[ktoso]

Some notes, overall great docs! Just need to flesh out a few confusing bits; the rest about what's allowed etc is great 👍

[ktoso]

I guess we may stick to Swift buzzwords here, we usually say "concurrency safety", and I amended a bit the wording with sendable. On that note, We should enable Swift 6 mode if we want to claim concurrency safety, the compiler will do more checks then

Suggested change

	- *Thread Safe*: Operations use internal locking and conform to `Sendable`.
	- *Concurrency Safe*: Operations are thread safe, and safety is expressed using Swift's concurrency safety mechanisms such as `Sendable`.

[incertum]

Simplified.

[ktoso]

Why wouldn't emit(into:) be thread safe, there's no reason for that 🤔

If you're concerned about someone concurrently calling with the same buffer -- swift won't allow that since that'd violate exclusive access with the inout enforces

I'd rephrase this section a bit, we don't need to explain Sendable to Swift developers here. Concurrency safety is kinda "expected" in Swift nowadays, however we should enable Swift 6 mode so we can prove we're safe :)

[incertum]

Will check, let's get back to it next week. Meanwhile quickly rebased. In general I suppose I still live too much in the C and C++ world ...

[ktoso]

I mean that Swift will literarily prevent such races:

func test() async { 
  var buffer: [UInt8] = []

  await Task { 
    emit(into: &buffer) // error: Sending value of non-Sendable type '() async -> ()' risks causing data races
  }.value
        
  await Task { 
    emit(into: &buffer)
  }.value
}

while the following is OK:

func test() async { 
  var buffer: [UInt8] = []

  await Task { 
    emit(into: &buffer)
  }.value
}

because the value is "sent" to that task and cannot be accessed from other contexts.

In Swift we lean heavily on compiler assured concurrency safety and it would be weird to call out a method is not safe like that, because it's context dependent and the compiler will prevent the racy versions of code :-)

This is an error in Swift 6 mode (or "complete concurrency checking), and a warning in 5 mode; there's no need to call out in our docs issues that the compiler will prevent.

[incertum]

Thank you! However, if it needs to be Sendable, you still need locking, just like we do with the internal buffer. I’ve rewritten this part of the documentation, so let me know!

[ktoso]

That's the thing -- there's no locking required if sendable analysis can prove it's not strictly needed or ensured otherwise -- see the capturing in the Task, or you could have a buffer in an actor and the collecting tasks be on the same actor etc... So yes, it needs to be safe and swift will enforce that but it doesn't explicitly mean a lock per se :)

[ktoso]

Looks good, nice updates @incertum !