What are all the secret functions and hints the Standard Library can use?

(Daryle Walker) #1

When I look at the code for the Standard Library, I see functions like _precondition, attributes like __consuming or @usableFromInline, and other stuff I don't recognize. I should probably use them in code to be submitted for the StdLib, but I don't know what all of them are, let alone what they do. Can they be listed & explained here? Or can I just ignore them, use regular Swift techniques, and have people who are more expert with these items tell be what needs to be done through comments and pull requests to my (eventual) pull requests?

(Jeremy David Giesbrecht) #2

@usableFromInline is not unique to the standard library. You can read about it in The Swift Programming Language here.

For the stuff unique to the standard library, there is a manual in the Swift repository.

(Steve Canon) #3

Some of them, like _precondition, correspond directly to the normal Swift functions of the same name, but work around limitations that prevent us from using the "normal" spelling in the standard library.

Some others, like @usableFromInline (https://github.com/apple/swift-evolution/blob/master/proposals/0193-cross-module-inlining-and-specialization.md) is totally normal outside the standard library, but new enough or specialized enough that you simply may not have encountered it yet.

There are also a bunch of things that are specific hooks for the standard library, most notably assertions and diagnostics and compiler hints that are enforced at different levels of optimization and debugging (things like _branchHint). Not all of these have "public" analogues, and they should be better documented (there may also be some redundancy between them, since they've been added in a somewhat ad hoc manner). I think there are a few where the documentation may be inaccurate or missing (this is a good beginner-ish project for someone to tackle, though you'll need to consult with team members for clarification), but most are discussed somewhat in the link that @SDGGiesbrecht posted above.

Definitely feel free to ask questions here if there are specific annotations that you want to learn about.

(Jordan Rose) #4

A smattering of these are found in the Standard Library Programmer's Manual too, though that's still pretty incomplete.

(Daryle Walker) #5

What does "__consuming" mean?

(Steve Canon) #6

__consuming is defined in the Ownership Manifesto (as consuming).

(Adrian Zubarev) #7

What is the difference between single underscore prefix and double underscore? “Hands off vs. hands off, now for real“? :raised_hands:

(Jordan Rose) #8

Heh, there's no real difference. I think it's mostly whether the keyword, attribute, or declaration was introduced by someone who was in a C/C++ mood at the time or not.

(Joe Groff) #9

I think we do at least systematically use double underscores for keywords to support unofficial language features, so that they're less likely to interfere with the parsing of code that's unaware of them.