Remove the unused swift_asyncLet_{start,end,wait,wait_throwing} runtime

functions.

These were introduced in an early draft implementation of async let, but
never used by a released compiler. They are not used as symbols by any
app binaries. There's no reason to keep carrying them.

While I'm at it, dramatically improve the documentation of the remaining
async let API functions.

Author: rjmccall

include/swift/ABI/MetadataValues.h

@@ -2910,9 +2910,9 @@ enum class TaskOptionRecordKind : uint8_t {
   InitialSerialExecutor = 0,
   /// Request a child task to be part of a specific task group.
   TaskGroup = 1,
-  /// DEPRECATED. AsyncLetWithBuffer is used instead.
+  /// UNUSED. AsyncLetWithBuffer is used instead.
   /// Request a child task for an 'async let'.
-  AsyncLet = 2,
+  // AsyncLet = 2,
   /// Request a child task for an 'async let'.
   AsyncLetWithBuffer = 3,
   /// Information about the result type of the task, used in embedded Swift.

include/swift/ABI/TaskOptions.h

@@ -166,25 +166,6 @@ class InitialSerialExecutorTaskOptionRecord : public TaskOptionRecord {
   }
 };
 
-/// DEPRECATED. AsyncLetWithBufferTaskOptionRecord is used instead.
-/// Task option to specify that the created task is for an 'async let'.
-class AsyncLetTaskOptionRecord : public TaskOptionRecord {
-  AsyncLet *asyncLet;
-
-public:
-  AsyncLetTaskOptionRecord(AsyncLet *asyncLet)
-    : TaskOptionRecord(TaskOptionRecordKind::AsyncLet),
-      asyncLet(asyncLet) {}
-
-  AsyncLet *getAsyncLet() const {
-    return asyncLet;
-  }
-
-  static bool classof(const TaskOptionRecord *record) {
-    return record->getKind() == TaskOptionRecordKind::AsyncLet;
-  }
-};
-
 class AsyncLetWithBufferTaskOptionRecord : public TaskOptionRecord {
   AsyncLet *asyncLet;
   void *resultBuffer;

include/swift/Runtime/Concurrency.h

@@ -351,24 +351,11 @@ bool swift_taskGroup_isCancelled(TaskGroup *group);
 SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swift)
 bool swift_taskGroup_isEmpty(TaskGroup *group);
 
-/// DEPRECATED. swift_asyncLet_begin is used instead.
-/// Its Swift signature is
+/// Enter the scope of an async let binding, creating a child task of the
+/// current task to run the given function.
 ///
-/// \code
-/// func swift_asyncLet_start<T>(
-///     asyncLet: Builtin.RawPointer,
-///     options: Builtin.RawPointer?,
-///     operation: __owned @Sendable () async throws -> T
-/// )
-/// \endcode
-SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swift)
-void swift_asyncLet_start(AsyncLet *alet,
-                          TaskOptionRecord *options,
-                          const Metadata *futureResultType,
-                          void *closureEntryPoint, HeapObject *closureContext);
-
-/// Begin an async let child task.
-/// Its Swift signature is
+/// Behaves approximately like a Swift function with the following
+/// signature, except the generic argument is in a different position:
 ///
 /// \code
 /// func swift_asyncLet_start<T>(
@@ -378,64 +365,24 @@ void swift_asyncLet_start(AsyncLet *alet,
 ///     resultBuffer: Builtin.RawPointer
 /// )
 /// \endcode
+///
+/// Previous versions of the concurrency runtime also provided a
+/// \c swift_asyncLet_start which did not take a result buffer. This
+/// function was never used by a released version of the compiler,
+/// and it has been removed.
 SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swift)
 void swift_asyncLet_begin(AsyncLet *alet,
                           TaskOptionRecord *options,
                           const Metadata *futureResultType,
                           void *closureEntryPoint, HeapObject *closureContext,
                           void *resultBuffer);
 
-/// This matches the ABI of a closure `<T>(Builtin.RawPointer) async -> T`
-using AsyncLetWaitSignature =
-    SWIFT_CC(swiftasync)
-    void(OpaqueValue *,
-         SWIFT_ASYNC_CONTEXT AsyncContext *, AsyncTask *, Metadata *);
-
-/// DEPRECATED. swift_asyncLet_get is used instead.
-/// Wait for a non-throwing async-let to complete.
+/// Get the value of a non-throwing async let, awaiting the result
+/// if necessary.
 ///
-/// This can be called from any thread. Its Swift signature is
+/// This must be called from the parent task of the async let.
 ///
-/// \code
-/// func swift_asyncLet_wait(
-///     _ asyncLet: _owned Builtin.RawPointer
-/// ) async -> Success
-/// \endcode
-SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swiftasync)
-void swift_asyncLet_wait(OpaqueValue *,
-                         SWIFT_ASYNC_CONTEXT AsyncContext *,
-                         AsyncLet *, TaskContinuationFunction *,
-                         AsyncContext *);
-
-/// DEPRECATED. swift_asyncLet_get_throwing is used instead.
-/// Wait for a potentially-throwing async-let to complete.
-///
-/// This can be called from any thread. Its Swift signature is
-///
-/// \code
-/// func swift_asyncLet_wait_throwing(
-///     _ asyncLet: _owned Builtin.RawPointer
-/// ) async throws -> Success
-/// \endcode
-SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swiftasync)
-void swift_asyncLet_wait_throwing(OpaqueValue *,
-                                  SWIFT_ASYNC_CONTEXT AsyncContext *,
-                                  AsyncLet *,
-                                  ThrowingTaskFutureWaitContinuationFunction *,
-                                  AsyncContext *);
-
-/// DEPRECATED. swift_asyncLet_finish is used instead.
-/// Its Swift signature is
-///
-/// \code
-/// func swift_asyncLet_end(_ alet: Builtin.RawPointer)
-/// \endcode
-SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swift)
-void swift_asyncLet_end(AsyncLet *alet);
-
-/// Get the value of a non-throwing async-let, awaiting the result if necessary.
-///
-/// This can be called from any thread. Its Swift signature is
+/// Behaves like a Swift async function with the signature:
 ///
 /// \code
 /// func swift_asyncLet_get(
@@ -444,21 +391,31 @@ void swift_asyncLet_end(AsyncLet *alet);
 /// ) async
 /// \endcode
 ///
-/// \c result points at the variable storage for the binding. It is
-/// uninitialized until the first call to \c swift_asyncLet_get or
-/// \c swift_asyncLet_get_throwing. That first call initializes the storage
-/// with the result of the child task. Subsequent calls do nothing and leave
-/// the value in place.
+/// except that it uses the special calling convention in which the
+/// continuation function, parent context, and child context are all
+/// passed in separately rather than being stored in the child context.
+/// The child async context has a fixed size of 5 * sizeof(void*).
+///
+/// \c resultBuffer must be the same result buffer that was passed to
+/// swift_asyncLet_begin. After asynchronous return, it is guaranteed
+/// to be initialized.
+///
+/// Previous versions of the concurrency runtime also provided a
+/// \c swift_asyncLet_wait which was meant to be paired with
+/// \c swift_asyncLet_start. This function was never used by
+/// a released version of the compiler, and it has been removed.
 SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swiftasync)
-void swift_asyncLet_get(SWIFT_ASYNC_CONTEXT AsyncContext *,
-                        AsyncLet *,
-                        void *,
-                        TaskContinuationFunction *,
-                        AsyncContext *);
+void swift_asyncLet_get(SWIFT_ASYNC_CONTEXT AsyncContext *parentContext,
+                        AsyncLet *alet,
+                        void *resultBuffer,
+                        TaskContinuationFunction *continuation,
+                        AsyncContext *childContext);
 
-/// Get the value of a throwing async-let, awaiting the result if necessary.
+/// Get the value of a throwing async let, awaiting the result if necessary.
 ///
-/// This can be called from any thread. Its Swift signature is
+/// This must be called from the parent task of the async let.
+///
+/// Behaves like a Swift async function with the signature:
 ///
 /// \code
 /// func swift_asyncLet_get_throwing(
@@ -467,42 +424,75 @@ void swift_asyncLet_get(SWIFT_ASYNC_CONTEXT AsyncContext *,
 /// ) async throws
 /// \endcode
 ///
-/// \c result points at the variable storage for the binding. It is
-/// uninitialized until the first call to \c swift_asyncLet_get or
-/// \c swift_asyncLet_get_throwing. That first call initializes the storage
-/// with the result of the child task. Subsequent calls do nothing and leave
-/// the value in place. A pointer to the storage inside the child task is
-/// returned if the task completes successfully, otherwise the error from the
-/// child task is thrown.
+/// except that it uses the special calling convention in which the
+/// continuation function, parent context, and child context are all
+/// passed in separately rather than being stored in the child context.
+/// The child async context has a fixed size of 5 * sizeof(void*).
+///
+/// \c resultBuffer must be the same result buffer that was passed to
+/// swift_asyncLet_begin. After asynchronous return, it is guaranteed
+/// to be initialized unless the operation throws by passing an error
+/// to the continuation function.
+///
+/// Previous versions of the concurrency runtime also provided a
+/// \c swift_asyncLet_wait_throwing which was meant to be paired with
+/// \c swift_asyncLet_start. This function was never used by
+/// a released version of the compiler, and it has been removed.
 SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swiftasync)
-void swift_asyncLet_get_throwing(SWIFT_ASYNC_CONTEXT AsyncContext *,
-                                 AsyncLet *,
-                                 void *,
-                                 ThrowingTaskFutureWaitContinuationFunction *,
-                                 AsyncContext *);
+void swift_asyncLet_get_throwing(SWIFT_ASYNC_CONTEXT AsyncContext *parentContext,
+                                 AsyncLet *alet,
+                                 void *resultBuffer,
+                                 ThrowingTaskFutureWaitContinuationFunction *
+                                   continuation,
+                                 AsyncContext *childContext);
 
-/// Exit the scope of an async-let binding. If the task is still running, it
-/// is cancelled, and we await its completion; otherwise, we destroy the
-/// value in the variable storage.
+/// Exit the scope of an async let binding that was created with
+/// swift_asyncLet_begin. If the child task is still running, it is
+/// cancelled, and the current task is suspended to await its completion.
 ///
-/// Its Swift signature is
+/// This must be called from the parent task of the async let.
+///
+/// Behaves like a Swift async function with the signature:
 ///
 /// \code
 /// func swift_asyncLet_finish(_ asyncLet: Builtin.RawPointer,
 ///                            _ resultBuffer: Builtin.RawPointer) async
 /// \endcode
+///
+/// except that it uses the special calling convention in which the
+/// continuation function, parent context, and child context are all
+/// passed in separately rather than being stored in the child context.
+/// The child async context has a fixed size of 5 * sizeof(void*).
+///
+/// \c resultBuffer must be the same result buffer that was passed to
+/// swift_asyncLet_begin.
+///
+/// Prior to asynchronous return, the value in the result buffer is
+/// destroyed (if present) and any memory initially allocated for the
+/// task is deallocated. Because swift_asyncLet_begin potentially
+/// allocates memory on the parent task's task allocator, the call to
+/// this function must be properly paired with the begin.
+///
+/// The async let is invalid after this call and cannot be used again.
+///
+/// Previous versions of the concurrency runtime also provided a
+/// \c swift_asyncLet_end which was not asynchronous and was meant
+/// to be paired with \c swift_asyncLet_start. This function was never
+/// used by a released version of the compiler, and it has been removed.
 SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swiftasync)
 void swift_asyncLet_finish(SWIFT_ASYNC_CONTEXT AsyncContext *,
                            AsyncLet *,
                            void *,
                            TaskContinuationFunction *,
                            AsyncContext *);
 
-/// Get the value of a non-throwing async-let, awaiting the result if necessary,
-/// and then destroy the child task. The result buffer is left initialized after
-/// returning.
+/// Get the value of a non-throwing async let binding that was created
+/// with \c swift_asyncLet_begin, awaiting the task's completion if
+/// necessary, and then destroy the task and the binding.
 ///
-/// This can be called from any thread. Its Swift signature is
+/// This must be called from the parent task of the async let.
+///
+/// Behaves like a Swift async function with the signature:
 ///
 /// \code
 /// func swift_asyncLet_get(
@@ -511,22 +501,34 @@ void swift_asyncLet_finish(SWIFT_ASYNC_CONTEXT AsyncContext *,
 /// ) async
 /// \endcode
 ///
-/// \c result points at the variable storage for the binding. It is
-/// uninitialized until the first call to \c swift_asyncLet_get or
-/// \c swift_asyncLet_get_throwing. The child task will be invalidated after
-/// this call, so the `async let` can not be gotten or finished afterward.
+/// except that it uses the special calling convention in which the
+/// continuation function, parent context, and child context are all
+/// passed in separately rather than being stored in the child context.
+/// The child async context has a fixed size of 5 * sizeof(void*).
+///
+/// \c resultBuffer must be the same result buffer that was passed to
+/// swift_asyncLet_begin. After asynchronous return, this is guaranteed
+/// to be initialized.
+///
+/// The async let is invalid after this call and cannot be used again.
+/// Any memory initially allocated for the task is deallocated. Because
+/// \c swift_asyncLet_begin potentially allocates memory on the parent
+/// task's task allocator, the call to this function must be properly
+/// paired with the begin.
 SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swiftasync)
-void swift_asyncLet_consume(SWIFT_ASYNC_CONTEXT AsyncContext *,
-                            AsyncLet *,
-                            void *,
-                            TaskContinuationFunction *,
-                            AsyncContext *);
+void swift_asyncLet_consume(SWIFT_ASYNC_CONTEXT AsyncContext *callerContext,
+                            AsyncLet *alet,
+                            void *resultBuffer,
+                            TaskContinuationFunction *continuation,
+                            AsyncContext *callContext);
 
-/// Get the value of a throwing async-let, awaiting the result if necessary,
-/// and then destroy the child task. The result buffer is left initialized after
-/// returning.
+/// Get the value of a throwing async let binding that was created
+/// with \c swift_asyncLet_begin, awaiting the task's completion if
+/// necessary, and then destroy the task and the binding.
 ///
-/// This can be called from any thread. Its Swift signature is
+/// This must be called from the parent task of the async let.
+///
+/// Behaves like a Swift async function with the signature:
 ///
 /// \code
 /// func swift_asyncLet_get_throwing(
@@ -535,18 +537,28 @@ void swift_asyncLet_consume(SWIFT_ASYNC_CONTEXT AsyncContext *,
 /// ) async throws
 /// \endcode
 ///
-/// \c result points at the variable storage for the binding. It is
-/// uninitialized until the first call to \c swift_asyncLet_get or
-/// \c swift_asyncLet_get_throwing. That first call initializes the storage
-/// with the result of the child task. Subsequent calls do nothing and leave
-/// the value in place. The child task will be invalidated after
-/// this call, so the `async let` can not be gotten or finished afterward.
+/// except that it uses the special calling convention in which the
+/// continuation function, parent context, and child context are all
+/// passed in separately rather than being stored in the child context.
+/// The child async context has a fixed size of 5 * sizeof(void*).
+///
+/// \c resultBuffer must be the same result buffer that was passed to
+/// swift_asyncLet_begin. After asynchronous return, it is guaranteed
+/// to be initialized unless the operation throws by passing an error
+/// to the continuation function.
+///
+/// The async let is invalid after this call and cannot be used again.
+/// Any memory initially allocated for the task is deallocated. Because
+/// \c swift_asyncLet_begin potentially allocates memory on the parent
+/// task's task allocator, the call to this function must be properly
+/// paired with the begin.
 SWIFT_EXPORT_FROM(swift_Concurrency) SWIFT_CC(swiftasync)
-void swift_asyncLet_consume_throwing(SWIFT_ASYNC_CONTEXT AsyncContext *,
-                                     AsyncLet *,
-                                     void *,
-                                     ThrowingTaskFutureWaitContinuationFunction *,
-                                     AsyncContext *);
+void swift_asyncLet_consume_throwing(SWIFT_ASYNC_CONTEXT AsyncContext *callerContext,
+                                     AsyncLet *alet,
+                                     void *resultBuffer,
+                                     ThrowingTaskFutureWaitContinuationFunction *
+                                       continuation,
+                                     AsyncContext *callContext);
 
 /// Returns true if the currently executing AsyncTask has a
 /// 'TaskGroupTaskStatusRecord' present.