sourcemod/core/systems/HandleSys.h

/**
 * vim: set ts=4 :
 * =============================================================================
 * SourceMod
 * Copyright (C) 2004-2008 AlliedModders LLC.  All rights reserved.
 * =============================================================================
 *
 * This program is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, version 3.0, as published by the
 * Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * As a special exception, AlliedModders LLC gives you permission to link the
 * code of this program (as well as its derivative works) to "Half-Life 2," the
 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
 * by the Valve Corporation.  You must obey the GNU General Public License in
 * all respects for all other code used.  Additionally, AlliedModders LLC grants
 * this exception to all derivative works.  AlliedModders LLC defines further
 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
 * or <http://www.sourcemod.net/license.php>.
 *
 * Version: $Id$
 */

#ifndef _INCLUDE_SOURCEMOD_HANDLESYSTEM_H_
#define _INCLUDE_SOURCEMOD_HANDLESYSTEM_H_

#include <IHandleSys.h>
#include <stdio.h>
#include "sm_globals.h"
#include "sm_trie.h"
#include "sourcemod.h"
#include "sm_memtable.h"

#define HANDLESYS_MAX_HANDLES		(1<<14)
#define HANDLESYS_MAX_TYPES			(1<<9)
#define HANDLESYS_MAX_SUBTYPES		0xF
#define HANDLESYS_SUBTYPE_MASK		0xF
#define HANDLESYS_TYPEARRAY_SIZE	(HANDLESYS_MAX_TYPES * (HANDLESYS_MAX_SUBTYPES + 1))
#define HANDLESYS_MAX_SERIALS		0xFFFF
#define HANDLESYS_SERIAL_MASK		0xFFFF0000
#define HANDLESYS_HANDLE_MASK		0x0000FFFF

#define HANDLESYS_MEMUSAGE_MIN_VERSION		3

/**
 *   The QHandle is a nasty structure that compacts the handle system into a big vector.
 * The members of the vector each encapsulate one Handle, however, they also act as nodes
 * in an inlined linked list and an inlined vector.
 *
 *   The first of these lists is the 'freeID' list.  Each node from 1 to N (where N
 * is the number of free nodes) has a 'freeID' that specifies a free Handle ID.  This
 * is a quick hack to get around allocating a second base vector.
 *
 *   The second vector is the identity linked list.  An identity has its own handle, so
 * these handles are used as sentinel nodes for index linking.  They point to the first and last
 * index into the handle array.  Each subsequent Handle who is owned by that identity is mapped into
 * that list.  This lets owning identities be unloaded in O(n) time.
 *
 *   Eventually, there may be a third list for type chains.
 */

enum HandleSet
{
	HandleSet_None = 0,
	HandleSet_Used,			/* The Handle is in use */
	HandleSet_Freed,		/* The "master" Handle of a clone chain is freed */
	HandleSet_Identity,		/* The Handle is a special identity */
};

struct QHandle
{
	HandleType_t type;			/* Handle type */
	void *object;				/* Unmaintained object pointer */
	IdentityToken_t *owner;		/* Identity of object which owns this */
	unsigned int serial;		/* Serial no. for sanity checking */
	unsigned int refcount;		/* Reference count for safe destruction */
	unsigned int clone;			/* If non-zero, this is our cloned parent index */
	HandleSet set;				/* Information about the handle's state */
	bool access_special;		/* Whether or not access rules are special or type-derived */
	bool is_destroying;			/* Whether or not the handle is being destroyed */
	HandleAccess sec;			/* Security rules */
	/* The following variables are unrelated to the Handle array, and used 
	 * as an inlined chain of information */
	unsigned int freeID;		/* ID of a free handle in the free handle chain */
	/* Indexes into the handle array for owner membership.
	 * For identity roots, these are treated as the head/tail. */
	unsigned int ch_prev;		/* chained previous handle */
	unsigned int ch_next;		/* chained next handle */
};

struct QHandleType
{
	IHandleTypeDispatch *dispatch;
	unsigned int freeID;
	unsigned int children;
	TypeAccess typeSec;
	HandleAccess hndlSec;
	unsigned int opened;
	int nameIdx;
};

typedef void (HANDLE_REPORTER)(const char *str, ...);

class HandleSystem : 
	public IHandleSys
{
	friend HandleError IdentityHandle(IdentityToken_t *token, unsigned int *index);
	friend class ShareSystem;
public:
	HandleSystem();
	~HandleSystem();
public: //IHandleSystem

	HandleType_t CreateType(const char *name,
		IHandleTypeDispatch *dispatch,
		HandleType_t parent,
		const TypeAccess *typeAccess,
		const HandleAccess *hndlAccess,
		IdentityToken_t *ident,
		HandleError *err);

	bool RemoveType(HandleType_t type, IdentityToken_t *ident);

	bool FindHandleType(const char *name, HandleType_t *type);

	Handle_t CreateHandle(HandleType_t type, 
		void *object,
		IdentityToken_t *owner,
		IdentityToken_t *ident,
		HandleError *err);

	HandleError FreeHandle(Handle_t handle, const HandleSecurity *pSecurity);

	HandleError CloneHandle(Handle_t handle, 
		Handle_t *newhandle, 
		IdentityToken_t *newOwner,
		const HandleSecurity *pSecurity);

	HandleError ReadHandle(Handle_t handle, 
		HandleType_t type, 
		const HandleSecurity *pSecurity,
		void **object);

	bool InitAccessDefaults(TypeAccess *pTypeAccess, HandleAccess *pHandleAccess);

	bool TypeCheck(HandleType_t intype, HandleType_t outtype);

	virtual Handle_t CreateHandleEx(HandleType_t type, 
		void *object,
		const HandleSecurity *pSec,
		const HandleAccess *pAccess,
		HandleError *err);

	void Dump(HANDLE_REPORTER rep);
protected:
	/**
	 * Decodes a handle with sanity and security checking.
	 */
	HandleError GetHandle(Handle_t handle, 
						  IdentityToken_t *ident, 
						  QHandle **pHandle, 
						  unsigned int *index,
						  bool ignoreFree=false);

	/**
	 * Creates a basic handle and sets its reference count to 1.
	 * Does not do any type or security checking.
	 */
	HandleError MakePrimHandle(HandleType_t type, 
							   QHandle **pHandle, 
							   unsigned int *index, 
							   HandleType_t *handle,
							   IdentityToken_t *owner,
							   bool identity=false);

	/**
	 * Frees a primitive handle.  Does no object freeing, only reference count, bookkeeping, 
	 * and linked list maintenance.
	 * If used on an Identity handle, destroys all Handles under that identity.
	 */
	void ReleasePrimHandle(unsigned int index);

	/**
	 * Sets the security owner of a type.
	 */
	void SetTypeSecurityOwner(HandleType_t type, IdentityToken_t *pToken);

	/**
	 * Helper function to check access rights.
	 */
	bool CheckAccess(QHandle *pHandle, HandleAccessRight right, const HandleSecurity *pSecurity);

	/** 
	 * Some wrappers for internal functions, so we can pass indexes instead of encoded handles.
	 */
	HandleError FreeHandle(QHandle *pHandle, unsigned int index);
	void UnlinkHandleFromOwner(QHandle *pHandle, unsigned int index);
	HandleError CloneHandle(QHandle *pHandle, unsigned int index, Handle_t *newhandle, IdentityToken_t *newOwner);
	Handle_t CreateHandleInt(HandleType_t type, void *object, const HandleSecurity *pSec, HandleError *err, const HandleAccess *pAccess, bool identity);

	bool TryAndFreeSomeHandles();
	HandleError TryAllocHandle(unsigned int *handle);
private:
	QHandle *m_Handles;
	QHandleType *m_Types;
	Trie *m_TypeLookup;
	unsigned int m_TypeTail;
	unsigned int m_FreeTypes;
	unsigned int m_HandleTail;
	unsigned int m_FreeHandles;
	unsigned int m_HSerial;
	BaseStringTable *m_strtab;
};

extern HandleSystem g_HandleSys;

#endif //_INCLUDE_SOURCEMOD_HANDLESYSTEM_H_