PawnPlus

PawnPlus v1.1
Download
Tutorials

What is this about?
PawnPlus is a multi-purpose plugin enhancing the capabilities of Pawn with features like asynchronous programming, dynamic containers and strings, threads, public and native functions hooks, and various other things.

Dynamic strings
Standard strings in Pawn are bound to an array allocated within the AMX. PawnPlus introduces dynamically allocated mutable strings which are not bound to any AMX instance, so they can be shared between scripts without copying, and offers a wide range of functions to manipulate them.

Using PawnPlus strings leads to better memory management (because you don't need to worry about the buffer size) and could increase the efficiency of some functions (because the length of the string is always known). PawnPlus strings can also store the null character without issues.

Moreover, any native function can be adapted to accept a dynamic string instead of a normal one. This transformation is very simple:

native SendClientMessageStr(playerid, color, AmxString:message) = SendClientMessage;

SendClientMessageStr(playerid, -1, str_new_static("Hello, id ")  str_val(playerid));

PawnPlus strings are garbage-collected, so you don't need to worry about their lifetime much.

Asynchronous programming
The usual way of handling events in Pawn is via a callback, even if the event is directly caused by the script. You may use inline functions from YSI, but the code is still scattered over multiple functions, despite the simple flow of actions.

In PawnPlus, you can represent an action that takes time using a task. In your code, you can call task_await which pauses the execution of the current functions (returning to the caller and not blocking the main thread) and resumes the code in the moment the task is completed.

A task can represent a MySQL query, the selection of an item from a dialog, a time interval or any time-based action you wish. You can create tasks, await them in one part of code and set the result in another, and the code resumes with the original variables preserved.

SendClientMessage(playerid, -1, "Loading...");
task_await(LoadPlayerAsync(playerid));
SendClientMessage(playerid, -1, "Loaded!");

task_await can be used on any task object, and if the task completes successfully, it returns the result. Tasks can also store AMX errors which you can use to signal exceptional results.

Dynamic containers
PawnPlus offers new efficient container types for use from Pawn: list (vector), linked list, and map. These containers can store values or arrays of any tag, which is stored together with the element as well. This allows for type-safe operations on these collections. You can even use strings as keys in a map.

Variant is another data type introduced in this plugin, which is used as the element type of dynamic collections. In containers, the variant has no identity (only value), but you can extract it from a collection without having to know its tag, and store it in another. Variants are also garbage collected.

All collections can be iterated using iterator objects. Iterators are objects pointing to a specific place in a collection, which can be used to access a single element in it, or to traverse the collection in a simple way. These iterators are safe to use even if the underlying collection is modified or deleted.

All collections are also available to be used as generic containers, restricting the type of values that are stored within. This feature is completely compile-time.

Tags
PawnPlus also extends the Pawn tag system with universally accessible tags, tag operations and tag inheritance. You can create a new dynamic tag, configure its operations, and set it as a tag of a variant, which allows you to call custom code when operations on the variant are performed. You can even override value copy and destruction, allowing you to introduce smart resource management.

Guards
Guards are special objects used to guard other values and destroy them when required. A guarded value will be destroyed when the context in which the guard was created terminates, freeing all resources that were associated with the value. You can set your own destructor via the tag system, and you'll never have to worry about freeing intermediate values ever again.

Threading
PawnPlus allows you to execute any piece of code in a new thread, parallel to the main one. Usually, the new thread will not allow other code to run in the same script (since AMX is not made for parallel execution), but together with forking, it is possible to clone the current script (preserving a specific selection of data) and execute a completely parallel code within it.

This can be combined with tasks to offload a time-consuming action to another thread, and provide a thread-safe method of retrieving the result.

Hooking
PawnPlus offers hooks of callbacks and native functions.

Any callback can be dynamically hooked with a new handler which is called when the original callback is called, and you can even modify the arguments or the return value. Combined with the task system, you can adapt any event-based code to task-based code with this approach.

Any native function can be hooked from your script, even affecting other scripts and plugins. Your code will be called every time when the original function is called, and you are free to modify the arguments or the return value in the same handler. You can even decide to hook a function only to modify some of its arguments and ignore the others, (via input filters), or to modify the return value only (via output filters).

Syntax shortcuts
Several functions can be used from new special pieces of syntax. For example, @ can be used as an alias for str_new_static, @@ can be used for str_val, await instead of task_await or yield instead of task_yield. New for loops are also provided for all collections, and there is special syntax for forked or threaded blocks.

All new syntax features are disabled by default because of to possible conflicts with other includes. You can enable them individually, or all of them by defining PP_SYNTAX.

Other stuff
You can obtain the list of all arguments given to the function, dynamically invoke natives or public functions, share variables in your script with other scripts, raise errors, catch errors, allocate memory on the heap, and fork the script (to protect its state from errors, for example, or to wait for a task locally without pausing the other code).


All these features are described in great detail on the GitHub wiki.