path: root/src/lua51/lobject.h

/*
** $Id: lobject.h,v 2.20.1.2 2008/08/06 13:29:48 roberto Exp $
** Type definitions for Lua objects
** See Copyright Notice in lua.h
*/


#ifndef lobject_h
#define lobject_h


#include <stdarg.h>


#include "llimits.h"
#include "lua.h"


/* tags for values visible from Lua */
#define LAST_TAG	LUA_TTHREAD

#define NUM_TAGS	(LAST_TAG+1)


/*
** Extra tags for non-values
*/
#define LUA_TPROTO	(LAST_TAG+1)
#define LUA_TUPVAL	(LAST_TAG+2)
#define LUA_TDEADKEY	(LAST_TAG+3)


/*
** Union of all collectable objects
*/
typedef union GCObject GCObject;


/*
** Common Header for all collectable objects (in macro form, to be
** included in other objects)
*/
// 需要垃圾回收的类型包含这个头，包含TString, Udata, Proto, UpVal, Closure, Table以及lua_State七个
//c next   指向下一个gc链表的成员
//c tt     数据类型
//c marked GC标记，用一个字节进行标记，在lgc.h
#define CommonHeader	GCObject *next; lu_byte tt; lu_byte marked


/*
** Common header in struct form
*/
typedef struct GCheader {
  CommonHeader;
} GCheader;




//c lua_TValue下第二高级的数据封装类型，不含数据类型标识
//c 包含需要GC的类型和不需要GC的类型
/*
** Union of all Lua values
*/
typedef union {
  GCObject *gc;
  void *p;
  lua_Number n;
  int b;
} Value;


/*
** Tagged Values
*/

//c 用在两个地方，lua_TValue和TKey
#define TValuefields	Value value; int tt

//c 最上层的Value类型，包含值和类型
typedef struct lua_TValue {
  TValuefields;
} TValue;


/* Macros to test type */
#define ttisnil(o)	(ttype(o) == LUA_TNIL)
#define ttisnumber(o)	(ttype(o) == LUA_TNUMBER)
#define ttisstring(o)	(ttype(o) == LUA_TSTRING)
#define ttistable(o)	(ttype(o) == LUA_TTABLE)
#define ttisfunction(o)	(ttype(o) == LUA_TFUNCTION)
#define ttisboolean(o)	(ttype(o) == LUA_TBOOLEAN)
#define ttisuserdata(o)	(ttype(o) == LUA_TUSERDATA)
#define ttisthread(o)	(ttype(o) == LUA_TTHREAD)
#define ttislightuserdata(o)	(ttype(o) == LUA_TLIGHTUSERDATA)

/* Macros to access values */
#define ttype(o)	((o)->tt)
#define gcvalue(o)	check_exp(iscollectable(o), (o)->value.gc)
#define pvalue(o)	check_exp(ttislightuserdata(o), (o)->value.p)
#define nvalue(o)	check_exp(ttisnumber(o), (o)->value.n)
#define rawtsvalue(o)	check_exp(ttisstring(o), &(o)->value.gc->ts)
#define tsvalue(o)	(&rawtsvalue(o)->tsv)
#define rawuvalue(o)	check_exp(ttisuserdata(o), &(o)->value.gc->u)
#define uvalue(o)	(&rawuvalue(o)->uv)
#define clvalue(o)	check_exp(ttisfunction(o), &(o)->value.gc->cl)
#define hvalue(o)	check_exp(ttistable(o), &(o)->value.gc->h)
#define bvalue(o)	check_exp(ttisboolean(o), (o)->value.b)
#define thvalue(o)	check_exp(ttisthread(o), &(o)->value.gc->th)

#define l_isfalse(o)	(ttisnil(o) || (ttisboolean(o) && bvalue(o) == 0))

/*
** for internal debug only
*/
#define checkconsistency(obj) \
  lua_assert(!iscollectable(obj) || (ttype(obj) == (obj)->value.gc->gch.tt))

#define checkliveness(g,obj) \
  lua_assert(!iscollectable(obj) || \
  ((ttype(obj) == (obj)->value.gc->gch.tt) && !isdead(g, (obj)->value.gc)))

//c 将TValue结构具体为对应的类型和值；即修改TValue的tt和value部分
/* Macros to set values */
#define setnilvalue(obj) ((obj)->tt=LUA_TNIL)

#define setnvalue(obj,x) \
  { TValue *i_o=(obj); i_o->value.n=(x); i_o->tt=LUA_TNUMBER; }

#define setpvalue(obj,x) \
  { TValue *i_o=(obj); i_o->value.p=(x); i_o->tt=LUA_TLIGHTUSERDATA; }

#define setbvalue(obj,x) \
  { TValue *i_o=(obj); i_o->value.b=(x); i_o->tt=LUA_TBOOLEAN; }

#define setsvalue(L,obj,x) \
  { TValue *i_o=(obj); \
    i_o->value.gc=cast(GCObject *, (x)); i_o->tt=LUA_TSTRING; \
    checkliveness(G(L),i_o); }

#define setuvalue(L,obj,x) \
  { TValue *i_o=(obj); \
    i_o->value.gc=cast(GCObject *, (x)); i_o->tt=LUA_TUSERDATA; \
    checkliveness(G(L),i_o); }

#define setthvalue(L,obj,x) \
  { TValue *i_o=(obj); \
    i_o->value.gc=cast(GCObject *, (x)); i_o->tt=LUA_TTHREAD; \
    checkliveness(G(L),i_o); }

#define setclvalue(L,obj,x) \
  { TValue *i_o=(obj); \
    i_o->value.gc=cast(GCObject *, (x)); i_o->tt=LUA_TFUNCTION; \
    checkliveness(G(L),i_o); }

#define sethvalue(L,obj,x) \
  { TValue *i_o=(obj); \
    i_o->value.gc=cast(GCObject *, (x)); i_o->tt=LUA_TTABLE; \
    checkliveness(G(L),i_o); }

#define setptvalue(L,obj,x) \
  { TValue *i_o=(obj); \
    i_o->value.gc=cast(GCObject *, (x)); i_o->tt=LUA_TPROTO; \
    checkliveness(G(L),i_o); }




#define setobj(L,obj1,obj2) \
  { const TValue *o2=(obj2); TValue *o1=(obj1); \
    o1->value = o2->value; o1->tt=o2->tt; \
    checkliveness(G(L),o1); }


/*
** different types of sets, according to destination
*/

/* from stack to (same) stack */
#define setobjs2s	setobj
/* to stack (not from same stack) */
#define setobj2s	setobj
#define setsvalue2s	setsvalue
#define sethvalue2s	sethvalue
#define setptvalue2s	setptvalue
/* from table to same table */
#define setobjt2t	setobj
/* to table */
#define setobj2t	setobj
/* to new object */
#define setobj2n	setobj
#define setsvalue2n	setsvalue

#define setttype(obj, tt) (ttype(obj) = (tt))


#define iscollectable(o)	(ttype(o) >= LUA_TSTRING)



typedef TValue *StkId;  /* index to stack elements */


//c 字符串
//c 每个字符串都需要计算hash，用来比较和查找字符串
//c 如果这个字符串已经存在，不再生成新的字符串，而是使用旧的
/*
** String headers for string table
*/
typedef union TString {
  L_Umaxalign dummy;  /* ensures maximum alignment for strings */
  struct {
    CommonHeader;
    lu_byte reserved;//c 标记字符串是否是lua的关键字，如果是，不会被GC回收
    unsigned int hash;//c 字符串的哈希值，比较字符串的依据
    size_t len; //c 字符串长度
  } tsv; //c tstring value
} TString;


#define getstr(ts)	cast(const char *, (ts) + 1)
#define svalue(o)       getstr(rawtsvalue(o))

//c userdata，和TString比较像
typedef union Udata {
  L_Umaxalign dummy;  /* ensures maximum alignment for `local' udata */
  struct {
    CommonHeader;
    struct Table *metatable;
    struct Table *env;
    size_t len;
  } uv;
} Udata;


//c! 函数原型，是沟通前端和后端（分析阶段和执行阶段）的数据
//c! 主要有 字节码、常量、局部变量、upvalue
/*
** Function Prototypes
*/
typedef struct Proto {
  CommonHeader;
	//c 常量表，能看出来lua保存常量的单元是函数原型，所有代码片段都会被编译为proto
  TValue *k;  /* constants used by the function */
	//c 这个函数的字节码
  Instruction *code;
	//c 这个函数内嵌套的函数
  struct Proto **p;  /* functions defined inside the function */
  int *lineinfo;  /* map from opcodes to source lines */
	//c 局部变量，在lparser.c > registerlocalvar注册
  struct LocVar *locvars;  /* information about local variables */
	//c upvalue表
  TString **upvalues;  /* upvalue names */
  TString  *source; //c 文件名，只有顶层函数有，内嵌函数这个字段是空的
  int sizeupvalues;
  int sizek;  /* size of `k' */
  int sizecode;
  int sizelineinfo;
  int sizep;  /* size of `p' */
  int sizelocvars;
  int linedefined;
  int lastlinedefined;
  GCObject *gclist;
  lu_byte nups;  /* number of upvalues */
  lu_byte numparams; //c 参数个数
  lu_byte is_vararg; //c 是否是可变参数...
  lu_byte maxstacksize; //c 最大栈大小, 通常200
} Proto;


/* masks for new-style vararg */
#define VARARG_HASARG		1
#define VARARG_ISVARARG		2
#define VARARG_NEEDSARG		4


//c 局部变量
typedef struct LocVar {
	//c 变量名，只会在编译器用到，存在FuncState结构，用来查找局部变量ID
  TString *varname; 
	//c 
  int startpc;  /* first point where variable is active */
  int endpc;    /* first point where variable is dead */
} LocVar;



/*
** Upvalues
*/
//c 判断upvalue是关闭的方式是 uv->v == &uv->u.value
// upvalue有开闭的概念
// 开是指upvalue完全由此方法所有，之前的调用已经结束
// 关闭是指upvalue还在之前的栈上
typedef struct UpVal {
  CommonHeader;
  TValue *v;  /* points to stack or to its own value */ //c upvalue的栈地址
  union {
    TValue value;  /* the value (when closed) */
    struct {  /* double linked list (when open) */
      struct UpVal *prev;
      struct UpVal *next;
    } l;
  } u;
} UpVal;
/*
* function func()
* 	local a = 10;
* 	local b = function()
* 		a = a + 1
* 		print(a)
* 	end
* 	b() -- 这个是开
* end
*
* function func()
* 	local a = 10;
* 	local b = function()
* 		a = a + 1
* 		print(a)
* 	end
* 	return b
* end
*
* fn = func()
* fn() -- 这个是关
*/


/*
** Closures
*/

#define ClosureHeader \
	CommonHeader; lu_byte isC; lu_byte nupvalues; GCObject *gclist; \
	struct Table *env

typedef struct CClosure {
  ClosureHeader;
	/*
	CommonHeader;  //c gc header
	lu_byte isC;   //c is c closure
	lu_byte nupvalues;  //c number of upvalues
	GCObject *gclist; //c gclist?
	struct Table *env //c 这个闭包的环境
	*/
  lua_CFunction f;
  TValue upvalue[1]; // upvalue
} CClosure;


typedef struct LClosure {
  ClosureHeader;
	/*
	CommonHeader;  //c gc header
	lu_byte isC;   //c is c closure
	lu_byte nupvalues;  //c number of upvalues
 	GCObject *gclist; //c gclist?
	struct Table *env //c 这个闭包的环境表，在luaF_newLclosure设置
	*/
  struct Proto *p; // lua闭包的函数原型
  UpVal *upvals[1]; // lua闭包的upvalue变长数组
} LClosure;


typedef union Closure {
  CClosure c;
  LClosure l;
} Closure;


//c 判断函数类型，5.2通过高位判断，在基础类型基础上产生变体 variant
#define iscfunction(o)	(ttype(o) == LUA_TFUNCTION && clvalue(o)->c.isC)
#define isLfunction(o)	(ttype(o) == LUA_TFUNCTION && !clvalue(o)->c.isC)


/*
** Tables
*/
//c 表的某个元素的key
typedef union TKey {
	//nk 用来拿到下一个node的指针
  struct {
    TValuefields; // 就是TValue
		//c 指向下一个node
    struct Node *next;  /* for chaining */
  } nk; // next key
	//tvk 用来拿本node的key值
  TValue tvk; // key value
} TKey;

//c 表的单个元素
typedef struct Node {
  TValue i_val;//value
  TKey i_key; //key
} Node;


//c 表
typedef struct Table {
  CommonHeader;
	// 标记这个表有哪些元方法，第一次查找时为0，如果有某个元方法，将对应位置为1
	// 下次查找时就不需要查找字符串了
	// flag会在luaH_set清空
  lu_byte flags;  /* 1<<p means tagmethod(p) is not present */ 
	// lsizenode=log2(length of hash table) 由此可知散列表大小一定是2的幂
	// 所以如果散列表要扩展，在原大小基础上扩展一倍
	// 要得到散列表大小，只需要移位 length of hash table = 1 << lsizenode
  lu_byte lsizenode;  /* log2 of size of `node' array */
	// 该表的元表
  struct Table *metatable;
	// 数组部分
  TValue *array;  /* array part */
	// 散列桶起始位置
	// 多个桶，桶内通过TKey->nk->next连接
  Node *node;
	// 空闲位置
  Node *lastfree;  /* any free position is before this position */
	// 在global_State中有关gc的链表的下一个（如果这个对象被加入了的话）
  GCObject *gclist;
	// 数组部分的大小
  int sizearray;  /* size of `array' array */
} Table;



//c 计算哈希值，用在很多地方
/*
** `module' operation for hashing (size is always a power of 2)
*/
#define lmod(s,size) \
	(check_exp((size&(size-1))==0, (cast(int, (s) & ((size)-1)))))


#define twoto(x)	(1<<(x))
#define sizenode(t)	(twoto((t)->lsizenode))


#define luaO_nilobject		(&luaO_nilobject_)

LUAI_DATA const TValue luaO_nilobject_;

#define ceillog2(x)	(luaO_log2((x)-1) + 1)

LUAI_FUNC int luaO_log2 (unsigned int x);
LUAI_FUNC int luaO_int2fb (unsigned int x);
LUAI_FUNC int luaO_fb2int (int x);
LUAI_FUNC int luaO_rawequalObj (const TValue *t1, const TValue *t2);
LUAI_FUNC int luaO_str2d (const char *s, lua_Number *result);
LUAI_FUNC const char *luaO_pushvfstring (lua_State *L, const char *fmt,
                                                       va_list argp);
LUAI_FUNC const char *luaO_pushfstring (lua_State *L, const char *fmt, ...);
LUAI_FUNC void luaO_chunkid (char *out, const char *source, size_t len);


#endif