After a PlatformFunction has been created, it can be called using one of these asynchronous protocols:

The number of arguments in the call must match the number of arguments in the PlatformFunction. The following sections describe how to make asynchronous calls using each of the protocols.

Standard asynchronous calls are created using the asyncCall... API. Use standard asynchronous calls when the value is required by a single process, and the process must wait until the call has completed. Standard asynchronous calls cause the current Smalltalk process to be suspended until the value is returned. Other Smalltalk processes continue to execute.

When an asynchronous call is made, an operating system thread is acquired, the current Smalltalk process suspends, and the platform function is executed in that thread. When the call completes, the result is posted back to Smalltalk, and the process that was waiting for the result resumes.

For example, given the following platform function on Windows:

the function would be called asynchronously as follows:

param1 is the argument to the call. The rc is the return value of the platform function (true/false), or an AcoError if an error occurred during the execution of the call. For a discussion of errors, see ACO errors and error cases.

When a standard asynchronous call is made during a system callback (that is when the operating system has called back into Smalltalk), the call is performed synchronously. Standard asynchronous calls are the fastest form of asynchronous call.

Resource future calls should be used if more than one process needs to wait on the return value or if the current process must continue executing until the return value is needed.

When a resource future call is made, a future is returned. This future can be queried for the state of the call while the platform function executes in a separate thread. If a process asks for the value of the future before the value is ready, the process is suspended. More than one process can wait on the return value of the future. When the call completes, the result is posted back to Smalltalk and the processes that are waiting on the result are resumed.

For example, to call a platform function using a resource future call:

param1 is the arguments to the call. The rc is the return value of the platform function (true/false), or an AcoError if an error occurred. The aFuture is a future that contains the result of the platform function. You must explicitly ask the future for its value. If the platform function has not yet completed, the process asking for the value of the platform function call blocks until the value is ready.

To check the status of a blocking call, the messages checkForValue or isReady can be sent to the future. The message checkForValue answers the return value if it is ready or an AcoError if it is not yet ready. The message isReady answers true if the return value is ready; otherwise, it answers false. When a future is asked for its value during a system callback (that is when the operating system has called back into Smalltalk), if the return value has not been calculated, then an AcoError is answered. Resource future calls are slower than standard asynchronous calls.

Like resource future calls, static future calls allow the current Smalltalk process to continue running until the return value is needed.

In addition, static future calls allow you to use the same operating system thread in more than one asynchronous call. The static future call does this by reserving a thread. This is useful when data is stored in the local memory for a thread. As a result, you must manage the resources by explicitly creating and destroying static futures and their resources. Allocating resources for static futures discusses the allocation and deallocation of resources.

To begin a static future call, the developer creates a static future and makes the call. When the call completes, the result is posted back to Smalltalk and processes waiting on the result are resumed. At this point, the developer may either reuse the static future or return its resources to the AcoResourceManager.

For example, to call a platform function using a static future call:

param1 is the parameters to the call. The rc is the return value of the platform function (true/false). The aFuture is a static future that contains the result of the platform function. You must explicitly ask the future explicitly for its value. If the platform function has not completed, the process asking for the value of a future blocks until the value is ready.

The static future can be reused for other platform function calls. These calls will be made in the same operating system thread. Once the developer no longer requires the static future, it must be returned to the AcoResourceManager.

To check the status of a blocking call, the messages checkForValue or isReady can be sent to the future. The message checkForValue answers the return value if it is ready or an AcoError if it is not ready. The message isReady answers true if the return value is ready; otherwise, it answers false.

Before a static future can be used in a subsequent call, the previous call must have completed. There are two protocols for determining this. Sending value to the future guarantees that the previous call has completed before the next starts because value waits until the call completes. When a static future is sent isAvailable, it answers true if the future is not involved in another asynchronous call and false if it is.

When a future is asked for its value during a system callback (that is when the operating system has called back into Smalltalk), if the return value has not been calculated, then an AcoError is answered.

Static future calls are slower than standard asynchronous calls, but faster than resource future calls.

The AcoResourceManager allocates and deallocates resources for a static future. Resources include the thread used to make the call and some fixed-space memory. To get the default resource manager, the message default is sent to the AcoResourceManager class. The default resource manager can then be sent the following messages to allocate and deallocate resources: