SDK Blocking Call Problems

Blocking calls

The "blocking" calls can only be made to SDK functions for which it is possible to register a callback. If a callback is not registered then these functions will wait (or, "block the caller") until the result has been received before returning.

Two common problems stem from the use of blocking calls in bots.

One is where blocking calls inside an event handler that appear to give the wrong results. The other is where attributes "magically" alter their values to something else.

Background

The SDK doesn't know in what order a bot wants to handle events and results so it will process them in the order they were received.

When an SDK function call is blocking it is waiting for the right type of result to be received. For example, it will wait for an aw_address result to be received if a blocking call to aw_address has been placed.

Any other types of results and all the events that are received when it waits will be processed. This means setting attributes to appropriate values and calling an event handler or callback if one has been registered.

You can think of a blocking SDK function call as it sending a request to the server and then calling a special version of aw_wait which will process everything until it receives a result of the correct type.

Attributes changing as if by magic

You should only assume that the attributes set by the blocking call (check the documentation for each function for a list of attributes) are defined when it returns.

Many of the other attributes could be changed by an event or result that was received while it waited.

Consider the following.

User A enters.

IP address of user A is queried.

User B says something.

User A is greeted with the name of user B.

Here is how it happened.

1. avatar_add event for user A was received.
2. Attributes are set and the event handler for avatar_add is called.
3. Blocking call to aw_address is placed for user A.
4. While waiting for the aw_address result, a chat event was received for user B.
5. Attributes are set and the event handler for chat is called (if one exists).

If you look at AW_EVENT_CHAT then you see that one of the attributes being set is AW_AVATAR_NAME.

6. The result for aw_address is received and the blocking call to aw_address for user A returns.
7. User A is greeted using the name in AW_AVATAR_NAME which is that of user B.

Blocking calls within event handlers

If the blocking call was placed inside an event handler then you can't even assume that the result you receive is the correct one.

Consider the following.

Bot is started, enters a world and makes itself visible.

Users A and B are within visible range of the bot.

User B is greeted with User A's IP address.

User A is greeted with user B's IP address.

Here is how it happened.

1. avatar_add event for user A was received and handle_avatar_add is called.
2. Name of user A is copied from AW_AVATAR_NAME to a local variable (to avoid having it "magically" altered).
3. A blocking call to aw_address is placed for user A.
4. avatar_add event was received for user B and handle_avatar_add is called.
5. Name of user B is copied from AW_AVATAR_NAME to a local variable.
6. A blocking call to aw_address is placed for user B.
7. The aw_address result for user A is received because it was requested first.
8. Blocking call to aw_address for user B returns and the IP address (of user A) is announced.
9. The aw_address result for user B is received because it was requested second.
10. Blocking call to aw_address for user A returns and the IP address (of user B) is announced.