WS_CALLBACK_MODEL enumeration (webservices.h)

Article
03/13/2023

Specifies the threading behavior of a callback (for example, a WS_ASYNC_CALLBACK).

Syntax

typedef enum {
  WS_SHORT_CALLBACK = 0,
  WS_LONG_CALLBACK = 1
} WS_CALLBACK_MODEL;

Constants


`WS_SHORT_CALLBACK` Value: 0 This value is used to indicate that a callback is invoked short. When a callback is invoked short, it should avoid lengthy computation or lengthy blocking calls so that it can return to the caller quickly. During the time that a callback is executing short, other work items may not be able to be dequeued within the process. This can lead to starvation deadlock, an unresponsive system, or an underutilized system. If it is necessary to do IO within a callback that was invoked short, the best practice is to use asynchronous IO (instead of synchronous IO), to avoid lengthy blocking calls.
`WS_LONG_CALLBACK` Value: 1 This value is used to indicate that a callback is invoked long. A callback invoked long is not required to return to the caller quickly. However, long callbacks are a limited resource, so it is not always possible to invoke a callback long. Before invoking a callback long, the caller must ensure that there is another thread available to dequeue work as necessary. For example, if a caller needs to create a thread but is unable to, then it must invoke the callback short. All callbacks must be able to deal with being invoked short as well as long: A callback that is invoked short but requires long can interpret this as an error condition, likely due to low resources. For example, calling CreateThread or QueueUserWorkItem in this situation is also likely to fail. If a callback is required to run long in a low resource situation, then a thread for this purpose must be reserved prior to initiating the async operation. A callback that is invoked long but expects short can go about its work normally.

WS_SHORT_CALLBACK
Value: 0
This value is used to indicate that a callback is invoked short.

When a callback is invoked short, it should avoid lengthy computation or lengthy
blocking calls so that it can return to the caller quickly. During the time
that a callback is executing short, other work items may not be able to be
dequeued within the process. This can lead to starvation deadlock, an
unresponsive system, or an underutilized system.

If it is necessary to do IO within a callback that was invoked short, the best practice is
to use asynchronous IO (instead of synchronous IO), to avoid lengthy blocking calls.

WS_LONG_CALLBACK
Value: 1
This value is used to indicate that a callback is invoked long.

A callback invoked long is not required to return to the caller quickly.

However, long callbacks are a limited resource, so it is not always possible
to invoke a callback long.

Before invoking a callback long, the caller must ensure that there is another thread
available to dequeue work as necessary. For example, if a caller needs to create
a thread but is unable to, then it must invoke the callback short.

All callbacks must be able to deal with being invoked short as well as long:

A callback that is invoked short but requires long can interpret this as an
error condition, likely due to low resources. For example, calling CreateThread or
QueueUserWorkItem in this situation is also likely to fail. If a
callback is required to run long in a low resource situation, then a thread
for this purpose must be reserved prior to initiating the async operation.

A callback that is invoked long but expects short can go about its work normally.

Remarks

Whether a callback will be invoked long or short is up to the caller implementation. The channel and listener implementations provide a way to control this for async callbacks via the WS_CHANNEL_PROPERTY_ASYNC_CALLBACK_MODEL and WS_LISTENER_PROPERTY_ASYNC_CALLBACK_MODEL properties.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2 [desktop apps \| UWP apps]
Header	webservices.h