Aw destroy
| Minimum requirements | ||
|---|---|---|
| Added in version 2.1 | ||
| SDK | build 13 | |
int aw_destroy (void)
Description
Destroys the current bot instance.
Callback
None (returns immediately)
Notes
This method destroys the current bot instance (i.e. the one returned by aw_instance). In a multi-instance application, call aw_instance_set first to set the instance to be destroyed.
A destroyed instance is only flagged as having been destroyed. The SDK will stop processing events, callbacks and method calls for it. Any resources allocated to it will be deallocated in aw_wait. Which means it is safe to call aw_destroy from within the context of an event handler or callback.
The most recently created instance will be set as the new current instance. If the destroyed instance is the most recently created then it will set the second most recent. If none exists then it will be set to NULL. It does not care if the new current instance has previously been destroyed.
Note that this method will immediately close any connection to a world/universe server. Nonblocking method calls placed shortly before calling it are not guaranteed to affect the server (e.g. aw_say ("I'm going!")). Such methods that lack a callback have no way of knowing when they have affected the server (within the heartbeat timeout).
For version 3.6 and earlier: This method will immediately deallocate all data structures related to the current instance. For this reason, it must only be called from the main event loop of an application. Do not call aw_destroy within the context of any event handler or callback.
Arguments
None
Argument attributes
None
Return values
Returned attributes
None
Usage
void handle_chat (void)
{
/* destroy the bot instance when someone tells it to quit */
if (strcmp (aw_string (AW_CHAT_MESSAGE), "quit") == 0)
{
/* immediately stop processing events and callbacks for the instance */
aw_destroy ();
/* ... */
}
}