[WIP] Add Distributed module documentation

[ktoso]

This is a very early version of Distributed module documentation; It is not polished up, may have stray sentences and sections etc.

We'll figure out how to best present the information through the pitch posted on the forums over here:

I'll also work on improving tone and voice still, right now it is not the most consistent.

For now, we can discuss what needs to be explained in this documentation and I started a forums thread for this purpose: TSPL Pitch: Distributed.

[martialln]

Mainly puts comments on the last section around Emulating callbacks as I found some errors in code examples

[martialln]

later is not a closure anymore and is async throws

Suggested change

	later("Here's the info you asked for!")
	try await later.additionalInfo("Here's the info you asked for!")

[martialln]

Suggested change

	protocol InfoListener: Codable {
	protocol InfoListener: DistributedActor, Codable {

[martialln]

Suggested change

	func additionalInfo(_ info: String) async throws
	distributed func additionalInfo(_ info: String)

[martialln]

Suggested change

	distributed func call(later: InfoListener) async -> String {
	distributed func call(later: some InfoListener) async -> String {

In this case Later concrete type must be known on Alice side.

[martialln]

Suggested change

	distributed actor Bob {
	distributed actor Bob: Codable {

[martialln]

We should explain that Alice and Bob must share the same ActorSystem. Also there are two cases: is Bob type known on Alice side or not

[martialln]

Suggested change

	print("later: \(laterReply)")
	print("later: \(info)")

[martialln]

Using resolvable protocol we could have something like that:

@Resolvable
protocol InfoListener: DistributedActor, Codable {
    distributed func additionalInfo(_ info: String)
}

distributed actor Alice {
    distributed func call(later: $InfoListener) async -> String {
        Task.detached {
            // do some asynchronous processing AFTER returning from the 'call' method...
            try await later.additionalInfo("Here's the info you asked for!")
        }
        
        return "Thanks for your call!"
    }
}

distributed actor Bob: DefaultDistributedActorSystem.SerializationRequirement {
    func test(alice: Alice) async throws {
        let infoListener = try $InfoListener.resolve(id: self.id, using: self.actorSystem)
        let immediateReply = try await alice.call(later: infoListener)
        
        print("immediately: \(immediateReply)")
    }
}

extension Bob: InfoListener {
    distributed func additionalInfo(_ info: String) {
        print("later: \(info)")
    }
}

[martialln]

Suggested change

	let immediateReply = try await alice.call(self)
	// We have to make sure, in some way, that the `DistributedCallback` instance stays alive to receive the callback
	let immediateReply = try await alice.call(later: DistributedCallback(name: "Bob", actorSystem: self.actorSystem))

[akbashev]

Overall like the page, gives a quick recap of the module!

Want to reread it a bit later with a fresh mind, but at the moment have two small comments. Added them as suggestions, but take them with a grain of salt.

1. Overall I think would be nice to add some small sentence on why exactly one should use distributed module.
2. Think memory management could also be highlighted—it's not quite obvious at a first glance. Though not sure about placing, it's quite specific. Maybe even be placed in Implementing Your Own DistributedActorSystem section as it's mostly for systems to care about?

[akbashev]

Suggested change

	In order to build distributed systems successfully you will need to get into the right mindset.
	Building distributed systems is a complex task that requires careful consideration of reliability, maintainability, and scalability. There are various approaches to build such systems, and Swift, as a general-purpose language, offers tools for this, such as actors. However, in order to build distributed systems successfully with this tools, you will need to get into the right mindset.

[akbashev]

Suggested change

	> Note: Be careful with memory management. Local actors already stored on the node, so it might be better to keep references to them as weak. However, for remote actors reference is generated, which could potentially be cleaned if not kept strongly. // TODO: Link to Automatic Reference Counting page?

[akbashev]

Suggested change

	way this method can fail, is by the underlying transport mechanism failing in sme way.
	way this method can fail, is by the underlying transport mechanism failing in some way.