NAME
	/obj/daemon/reclaimd.c - register objects for automatic reclaiming

DEFINITIONS
	superenvironment
	  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.

DESCRIPTION
	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 registrated object if supenv contains no living.
	Destruct registrated object if supenv contains no player.
	Destruct registrated 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 half an hour, in a statistical mean, but
	can be as short as 20 and as long as 40 minutes.

USEFUL FUNCTIONS
	register
	de_register
	query_registrated
	query_registrated_clone

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

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

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'.
		
NOTE
	Only objects in /players/... 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.

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

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

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

	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.

=========================================================================
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'.

=========================================================================
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.

=========================================================================
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.

=========================================================================

Help topics available:

area_d.doc

examples/

reclaimd.doc

timed.doc

wedd.doc