Design Guidelines

[mattmassicotte]

I'm not certain if this belongs in "Common Errors", or more something else. But I'd really like to expand on the trade-offs of fine- vs coarse-grained isolation.

For example:

class SomeClass {
    @MainActor
    var isolatedValue = 1
}

vs

actor SomeClass {
    @MainActor
    var isolatedValue = 1
}

vs

@MainActor
class SomeClass {
    var isolatedValue = 1
}

Especially to tie in the use of nonisolated for selectively opting-out of whatever domain your type is part of.

[mattmassicotte]

@hborla do you have any ideas on this?

[hborla]

@mattmassicotte I agree with you that this doesn't belong in Common Compiler Errors. Perhaps we need another section on API design. I've been thinking about expanding the Swift API Design Guidelines with concurrency guidelines, but that probably needs more explanation than what typically goes in that guide. I think it makes sense to add a section specifically about API changes and the implications in the migration guide, and this topic would fit into there. Thoughts?

[mattmassicotte]

Anedotally, I see many people looking for help with design. This is a pretty natural extension of the common errors section too. That helps you understand what's up. But, if you need/want to make deeper changes, having some recommendations to look at could be really useful.

I have not read the Swift API Design Guidelines. I agree that adding something to that guide could make sense. But, I also think you are right that these kinds of issues could be more involved. Plus, it would spread some very related information around.

"API Design"? "Design Guidelines"?

[mattmassicotte]

I'm co-opting this issue to represent the ideas that might go into #46.

Some things off the top of my head:

• Swift 5 + warnings first, or right to Swift 6?
• expressing truth first, then refactor/introduce more concurrency second
• Dynamic vs static isolation
• How should static isolation be structured (ie the original topic of "isolation granularity")
• Starting at leaf modules, top-level code, someting else?
• Fear of MainActor vs dealing with potentially-long-running synchronous code
• Changing classes into actors without careful thought
• Adding Sendable conformances to reference types to workaround awkward isolation

Some of this stuff does appear in other areas already, but might not be terrible to re-iterate.

[mattmassicotte]

InferSendableFromCaptures could be really important to mention as well.

[mattmassicotte]

I split this up becuase the migratio guidance document was getting quite large. However, I still do think there are some useful tips to include:

• MainActor + nonisolated
• Changing classes into actors
• Adding Sendable conformances to reference types to workaround awkward isolation
• Using multiple isolation domains within a single type