From the NannyMUD documentation

LAST CHANGE

2001-09-09

NAME

        reclaimd - Register objects for automatic reclaiming.

DESCRIPTION

        Don't inherit the reclaimd, use its functions like this intead:
	"/obj/daemon/reclaimd"->function_name(arguments);

	DEFINITION

        A superenvironment, or supenv for short, is a set of all the

        environments of an object. Consider a torch in a bag on a player in
        a room. The supenv of the torch is then the set (bag, player, room),
        the supenv of the player is the set (room), which then happens to be
        identical to the environment itself.

	RECLAIMD

        The reclaim daemon, reclaimd, maintains a list of objects, and checks
        on them now and then. The objects are registered with the daemon and
        their treatment at the checks can be customized. Possible actions are:

        Destruct registered object if supenv contains no living.
        Destruct registered object if supenv contains no player.
        Destruct registered object no matter what.
        No action.
        All of the above depending on returned value of a function call.

        For more detailed descriptions of the actions etc, see below.
	The time between checks is 15 minutes, in a statistical mean.

FUNCTIONS

QUERY FUNCTIONS

        query_registered
        query_registered_clone

OTHER FUNCTIONS

	register
	de_register

FUNCTION

NAME
        register - 


SYNTAX
varargs int register(object what, int time, mixed action)

DESCRIPTION
        This function registers an object to be checked on periodically. The
        arguments are:
        
        what    The object to be checked.
        time    The time in seconds that have to pass before any check is
                done. This should be given as 'time from now'; a value of
                3600 means 'an hour from now'.
        action  This can be either a small integer, or a string. In the case
                of integers:

                0 : destruct the object if it has no living supenv
                1 : destruct the object if it has no interactive (i.e.
                    player) supenv.
                2 : destruct the object.
                3 : take no action. This has little meaning here, but see
                    below for a better use.

                In the case of strings:

                "@func(arg1,arg2,...)"
                    The function 'func' in the registrated object is called
                    with the registrated object as first argument and 'arg1',
                    'arg2', etc. as argument 2, 3 ... A max number of nine
                    such arguments will be handled. The registrated object is
                    then treated in a way depending on the value returned from
                    the function call. For specifics, see above.

                    By using this mechanism and returning 3 from the function,
                    it is possible to keep an object registrated until the
                    game goes down. Kindly do not. Rather, return something
                    else than 3 after a few calls has been done.

                "@path->func(arg1,arg2,...)"
                    This works as above, apart from the call being made to the
                    object described by 'path'.


RETURN VALUES
        1 is returned if the object was sucessfully registrated.
        0 is returned if the object was not sucessfully registrated.


NOTE
        Only objects in /players, /std and /guilds can be registrated, and the
        registrating object must reside in the same dir-tree as the registrated
        object. In case of the action calling a function in another object,
        this is true for that object too.

        The file name will be expanded as per the sfun expand_file_name; thus
        it is relative /obj/daemon/, where the reclaimd resides. You are
        advised to use file names such as ~mym/monsters/doggie and such.


EXAMPLE
        register(sword, 3600)
        register(sword, 3600, 0)
          The sword will be destructed after at least 3600 seconds if it has
          no living supenv.


EXAMPLE
        register(axe, 7200+random(3600), 1)
          The sword will be destructed after at least 7200+random(3600)
          seconds if it has no interactive supenv.


EXAMPLE
        register(unique, 7500, 2)
          The sword will be destructed after at least 7500 seconds.


EXAMPLE
        reqister(call_me, 2400, "@call_back()")
          The function 'call_back' in the object 'call_me' will be called
          after at least 2400 seconds.


EXAMPLE
        register(item, 0, "@dest_me()")
          The function 'dest_me' in the object itself will be called at the
          next reclaim sweep.


EXAMPLE
        register(item, 3500, "@~/temple/stairs->check(key)")
          The function 'check' in '/players//temple/stairs' will be
          called after at least 3600 seconds with the object 'item' as first
          argument and the string "key" as second argument.




FUNCTION

NAME
        de_register - 

SYNTAX
void de_register(object obj)

DESCRIPTION
        Remove the object 'obj' from the check-list. The same restrictions
        are applied as for calls to the function 'register'.




FUNCTION

NAME
        query_registered - 

SYNTAX
int query_registered(object obj)

DESCRIPTION
        If the object 'obj' is registrated, this function returns 1, else
        it returns 0. This can be used for easy checks on unique items.




FUNCTION

NAME
        query_registered_clone - 

SYNTAX
int query_registered_clone(string file_name)

DESCRIPTION
        If there's a clone of the object described by 'file_name' in the list
        of registered objects, this function returns 1 else 0.