[TUT] The Use of Stocks

[Archive-Poster]

What is a stock? Many people don't understand at all, and that's why I'm writing this.

A stock is basically a function or variable that, if not used anywhere in the script, is simply ignored by the compiler.

Many people have the idea of doing this:

Code: Select all

#include <amxmodx>
#include <amxmisc>

public plugin_init()
{
    register_plugin("The","Matrix","Has You")
    
    fnDoFunc()
}

stock fnDoFunc()
    log_amx("the world has imploded upon itself")

When in fact you could achieve the same functionality through using this:

Code: Select all

#include <amxmodx>
#include <amxmisc>

public plugin_init()
{
    register_plugin("The","Matrix","Has You")
    
    fnDoFunc()
}

fnDoFunc()
    log_amx("the world has imploded upon itself")

So why are stocks used? Mostly for include files, where there are many functions and variables that are not used.

Taken straight from engine_stocks.inc:

Code: Select all

stock fakedamage(idvictim,szClassname[],Float:takedmgdamage,damagetype)
{
    new entity = create_entity("trigger_hurt")
    if (entity)
    {
        DispatchKeyValue(entity,"classname","trigger_hurt")
        new szDamage[16]
        // Takedamages only do half damage per attack (damage is damage per second, and it's triggered in 0.5 second intervals).
        // Compensate for that.
        format(szDamage,15,"%f",takedmgdamage * 2)
        DispatchKeyValue(entity,"dmg",szDamage)
        format(szDamage,15,"%i",damagetype)
        DispatchKeyValue(entity,"damagetype",szDamage)
        DispatchKeyValue(entity,"origin","8192 8192 8192")
        DispatchSpawn(entity)
        entity_set_string(entity, EV_SZ_classname, szClassname)
        fake_touch(entity,idvictim)
        remove_entity(entity)
        return 1
    }
    return 0
}

//wrapper for find_ent_by_class
stock find_ent(iStart, szClassname[])
{
    return find_ent_by_class(iStart, szClassname)
}

So, let's say I use find_ent somewhere in my script (which I am not condoning, it is a deprecated function for backward compatibility with AMX). The find_ent function will be included in the overhead and execution of my script, but fakedamage will not be because it was not used anywhere.

Stocks, as said twice above, can also be used on variables as such:

Code: Select all

stock const mystring[] = "hello pm"

Again, including this in your script is useless, but it is useful for an include file where a variable may or may not be used, without using a #define due to issues with pushing it onto the stack each time it is used.

That's basically what stocks are and why they are useful.

[Archive-Poster]

Stocks are not public. Furthermore, they are always parsed by the compiler ('stock' doesn't mean the compiler simply ignores it). The only difference between a stock and a normal function is that if it is unreferenced at assembly time, it is not included into the final code.

This is ideal for include files where users might not be using everything, and variables that might not be used

[Archive-Poster]

The only difference between a stock and a normal function is that if it is unreferenced at assembly time, it is not included into the final code.

[Archive-Poster]

They both function exactly the same if and when they are called; the only difference is when you compile the plugin. A stock function is only compiled into the binary (.amxx) file if it is called at least one time in your code. If it is not called at all, the compiler does not include that function in the compiled plugin.

As BAILOPAN said, stocks are ideal for include files since they contain numerous functions, some of which may never be used by the plugin that 'included' it. This will prevent the compiled plugin from containing code that is never used\executed at all.