Merge remote-tracking branch 'baidu_tera/master' into seq

Makefile

@@ -11,7 +11,7 @@ SHARED_CFLAGS = -fPIC
 SHARED_LDFLAGS = -shared -Wl,-soname -Wl,
 
 INCPATH += -I./src -I./include -I./src/leveldb/include -I./src/leveldb \
-		   -I./src/sdk/java/native-src $(DEPS_INCPATH) 
+		   -I./src/sdk/java/native-src $(DEPS_INCPATH)
 CFLAGS += $(OPT) $(SHARED_CFLAGS) $(INCPATH)
 CXXFLAGS += $(OPT) $(SHARED_CFLAGS) $(INCPATH)
 LDFLAGS += -rdynamic $(DEPS_LDPATH) $(DEPS_LDFLAGS) -lpthread -lrt -lz -ldl
@@ -33,6 +33,7 @@ COMMON_SRC := $(wildcard src/common/base/*.cc) $(wildcard src/common/net/*.cc) \
               $(wildcard src/common/file/*.cc) $(wildcard src/common/file/recordio/*.cc)
 SERVER_SRC := src/tera_main.cc src/tera_entry.cc
 CLIENT_SRC := src/teracli_main.cc
+TERA_C_SRC := src/tera_c.cc
 MONITOR_SRC := src/monitor/teramo_main.cc
 MARK_SRC := src/benchmark/mark.cc src/benchmark/mark_main.cc
 TEST_SRC := src/utils/test/prop_tree_test.cc src/utils/test/tprinter_test.cc src/io/test/tablet_io_test.cc
@@ -50,28 +51,31 @@ OTHER_OBJ := $(OTHER_SRC:.cc=.o)
 COMMON_OBJ := $(COMMON_SRC:.cc=.o)
 SERVER_OBJ := $(SERVER_SRC:.cc=.o)
 CLIENT_OBJ := $(CLIENT_SRC:.cc=.o)
+TERA_C_OBJ := $(TERA_C_SRC:.cc=.o)
 MONITOR_OBJ := $(MONITOR_SRC:.cc=.o)
 MARK_OBJ := $(MARK_SRC:.cc=.o)
 TEST_OBJ := $(TEST_SRC:.cc=.o)
 ALL_OBJ := $(MASTER_OBJ) $(TABLETNODE_OBJ) $(IO_OBJ) $(SDK_OBJ) $(PROTO_OBJ) \
            $(JNI_TERA_OBJ) $(OTHER_OBJ) $(COMMON_OBJ) $(SERVER_OBJ) $(CLIENT_OBJ) \
-           $(MONITOR_OBJ) $(MARK_OBJ) $(TEST_OBJ)
+           $(TERA_C_OBJ) $(MONITOR_OBJ) $(MARK_OBJ) $(TEST_OBJ)
 LEVELDB_LIB := src/leveldb/libleveldb.a
+TERA_C_SO = libtera_c.so
 
 PROGRAM = tera_main teracli teramo
 LIBRARY = libtera.a
 JNILIBRARY = libjni_tera.so
 BENCHMARK = tera_bench tera_mark
-TESTS = prop_tree_test tprinter_test
+TESTS = prop_tree_test tprinter_test string_util_test
+
 
 .PHONY: all clean cleanall test
 
-all: $(PROGRAM) $(LIBRARY) $(JNILIBRARY) $(BENCHMARK) $(TESTS)
+all: $(PROGRAM) $(LIBRARY) $(TERA_C_SO) $(JNILIBRARY) $(BENCHMARK) $(TESTS)
 	mkdir -p build/include build/lib build/bin build/log build/benchmark
 	mkdir -p $(UNITTEST_OUTPUT)
 	mv $(TESTS) $(UNITTEST_OUTPUT)
 	cp $(PROGRAM) build/bin
-	cp $(LIBRARY) $(JNILIBRARY) build/lib
+	cp $(LIBRARY) $(TERA_C_SO) $(JNILIBRARY) build/lib
 	cp src/leveldb/tera_bench .
 	cp -r benchmark/*.sh $(BENCHMARK) build/benchmark
 	cp src/sdk/tera.h build/include
@@ -81,12 +85,12 @@ all: $(PROGRAM) $(LIBRARY) $(JNILIBRARY) $(BENCHMARK) $(TESTS)
 check: $(TESTS)
 	( cd $(UNITTEST_OUTPUT); \
 	for t in $(TESTS); do echo "***** Running $$t"; ./$$t || exit 1; done )
-	$(MAKE) check -C src/leveldb 
+	$(MAKE) check -C src/leveldb
 
 clean:
 	rm -rf $(ALL_OBJ) $(PROTO_OUT_CC) $(PROTO_OUT_H) $(TEST_OUTPUT)
 	$(MAKE) clean -C src/leveldb
-	rm -rf $(PROGRAM) $(LIBRARY) $(JNILIBRARY) $(BENCHMARK) $(TESTS)
+	rm -rf $(PROGRAM) $(LIBRARY) $(TERA_C_SO) $(JNILIBRARY) $(BENCHMARK) $(TESTS)
 
 cleanall:
 	$(MAKE) clean
@@ -100,6 +104,10 @@ tera_main: $(SERVER_OBJ) $(LEVELDB_LIB) $(MASTER_OBJ) $(TABLETNODE_OBJ) \
 libtera.a: $(SDK_OBJ) $(PROTO_OBJ) $(OTHER_OBJ) $(COMMON_OBJ)
 	$(AR) -rs $@ $(SDK_OBJ) $(PROTO_OBJ) $(OTHER_OBJ) $(COMMON_OBJ)
 
+libtera_c.so: $(TERA_C_OBJ) $(SDK_OBJ) $(PROTO_OBJ) $(OTHER_OBJ) $(COMMON_OBJ)
+	$(CXX) -o $@ $(TERA_C_OBJ) $(SDK_OBJ) $(PROTO_OBJ) $(OTHER_OBJ) $(COMMON_OBJ) $(SHARED_LDFLAGS) \
+	-Xlinker "-(" $(LDFLAGS) -Xlinker "-)"
+
 teracli: $(CLIENT_OBJ) $(LIBRARY)
 	$(CXX) -o $@ $(CLIENT_OBJ) $(LIBRARY) $(LDFLAGS)
 
@@ -108,9 +116,9 @@ teramo: $(MONITOR_OBJ) $(LIBRARY)
 
 tera_mark: $(MARK_OBJ) $(LIBRARY) $(LEVELDB_LIB)
 	$(CXX) -o $@ $(MARK_OBJ) $(LIBRARY) $(LEVELDB_LIB) $(LDFLAGS)
- 
-libjni_tera.so: $(JNI_TERA_OBJ) $(LIBRARY) 
-	$(CXX) -shared $(JNI_TERA_OBJ) -Xlinker "-(" $(LIBRARY) $(LDFLAGS) -Xlinker "-)" -o $@ 
+
+libjni_tera.so: $(JNI_TERA_OBJ) $(LIBRARY)
+	$(CXX) -shared $(JNI_TERA_OBJ) -Xlinker "-(" $(LIBRARY) $(LDFLAGS) -Xlinker "-)" -o $@
 
 src/leveldb/libleveldb.a: FORCE
 	$(MAKE) -C src/leveldb
@@ -119,10 +127,13 @@ tera_bench:
 
 # unit test
 prop_tree_test: src/utils/test/prop_tree_test.o $(LIBRARY)
-	$(CXX) -o $@ $^ $(LDFLAGS) 
+	$(CXX) -o $@ $^ $(LDFLAGS)
 
 tprinter_test: src/utils/test/tprinter_test.o $(LIBRARY)
-	$(CXX) -o $@ $^ $(LDFLAGS) 
+	$(CXX) -o $@ $^ $(LDFLAGS)
+
+string_util_test: src/utils/test/string_util_test.o $(LIBRARY)
+	$(CXX) -o $@ $^ $(LDFLAGS)
 
 tablet_io_test: src/io/test/tablet_io_test.o src/tabletnode/tabletnode_sysinfo.o\
 		$(IO_OBJ) $(PROTO_OBJ) $(OTHER_OBJ) $(COMMON_OBJ) $(LEVELDB_LIB)
@@ -139,8 +150,8 @@ FORCE:
 
 .PHONY: proto
 proto: $(PROTO_OUT_CC) $(PROTO_OUT_H)
- 
+
 %.pb.cc %.pb.h: %.proto
 	$(PROTOC) --proto_path=./src/proto/ --proto_path=$(PROTOBUF_INCDIR) \
                   --proto_path=$(SOFA_PBRPC_INCDIR) \
-                  --cpp_out=./src/proto/ $< 
+                  --cpp_out=./src/proto/ $<

README.md

@@ -50,6 +50,9 @@ sh ./build.sh
 #反馈与技术支持
 [email protected]
 
+#成为贡献者
+完成[5个小任务](https://github.com/baidu/tera/blob/master/doc/to_be_a_contributor.md),帮你一步步成为tera贡献者.
+
 #欢迎加入
 如果你热爱开源，热爱分布式技术，请将简历发送至： 
 [email protected]

doc/UserManual.md

@@ -0,0 +1,40 @@
+#基本介绍
+## Tera是什么
+Tera是一个分布式结构化数据库,Tera中的数据以“表”为单位存放数据,每个表包含若干条"记录",每条记录包含一个"行健"(RowKey)和若干"列"，记录间按行健有序,行健可以是任意字符串,每列都包含一个"列名"(Column)和若干个"列值"(Value),多个每个列值上都附有一个时间戳(Timestamp).
+
+## Tera适用于怎样的场景  
+Tera适用于需要数据持久存储,并需要高效顺序或随机访问的场景. Tera将数据存储在分布式文件系统上,保证了数据的持久化,将数据按行健\列名\时间戳有序组织,保证了高效的顺序访问,实现了稠密索引,将热数据放在多级缓存(内存\SSD)中,保证了高效随机访问.
+
+## Tera的单机性能  
+因为不同场景硬件环境\数据压缩比\数据格式不同,性能数据会有较大差别,这里只能给出一个大概的值,可以认为是在16核心CPU,128G内存,2块SSD,6块Sata磁盘的服务器下的性能:
+顺序写80MB/S,随机写10MB/S,顺序读性能100MB/S,随机读1万QPS(SSD),500QPS(磁盘)
+
+## Tera的扩展性  
+Tera可以将单机性能水平扩展至几千台机器,在当前生产环境中,Tera单机群2000台机器.
+
+# 使用Tera
+## 编译、搭建
+编译Tera，参考[构建Tera](https://github.com/baidu/tera/blob/master/BUILD)  
+搭建Tera，参考[集群搭建](https://github.com/baidu/tera/blob/master/doc/cluster_setup.md)  
+Tera的配置说明，参考[tera_flag.md](https://github.com/baidu/tera/blob/master/doc/tera_flag.md)  
+TeraClient使用，参考[teracli.md](https://github.com/baidu/tera/blob/master/doc/teracli.md)  
+TeraSDK使用，参考[API使用方法](https://github.com/baidu/tera/wiki/%E4%B8%BB%E8%A6%81API%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95)  
+
+## 使用注意事项  
+1. 注意Rowkey的设计,避免全局的顺序写入.  
+因为Tera表是全局序的,Tera将一个表格按rowkey划分成多个区间,如果用当前时间作为rowkey,会导致所有的写操作都落入最后一个区间,相当于只有一台机器在服务,完全无法发挥出集群的性能.Tera的按负载自动分片无法解决这个问题,因为无论怎么分,用户都只写入最后一个分片.  
+2. 尽量选择IO性能高的机器搭建tera的TabletServer.  
+Tera是个存储系统,Tera的持久存储DFS和Tera本身的cache系统都会直接访问磁盘,TabeltServer上的读写操作多数也要通过读写磁盘实现,所以磁盘的IO性能决定了Tera对外提供的读写吞吐. 所以搭建tera的机器最好能拥有SSD作为TabletServer的本地cache,用于多块磁盘作为DFS的数据存储介质.虽然Tera在只有单块磁盘的机器上也可以搭建运行,也可以发挥出这台机器的最大存储性能.  
+
+## Tera使用FAQ  
+1. LG，CF，都是什么概念，划分原则是什么样的？  
+CF即Columnfamily、列族。在常规数据库中，需要在创建表时确定都包含哪些列，运行中不能随意更改。而Tera为了提供了动态Schema，让用户可以随意增删列，同时又保证让访问控制有迹可循，所以将常规数据库中的列拆成了Columnfamily、Qualifier两个维度，Columnfamily是访问控制的最小单位，必须在创建表时指定。Qualifier是tera中实际的列，用户可以在运行期随意创建和删除，但Qualifier必须从属于某个Columnfamliy，便于确定归属和进行访问控制。  
+LG即Localitygroup、局部性群组，是对存储的一个优化。设想，我们可以将所有的列族存储在一起，但这样我们要单独访问一个列族时，效率就不够高，我们也可以将每个列族都单独存储，这样要单独访问一个列族效率很高，但要同时访问一行（或者同时访问多个列族）效率就会很低。所以在这里做了一个折衷，我们将一些经常要一起访问的列族存储在一起，成为一个Localitygroup，而经常单独访问的列族，可以单独作为一个Localitygroup存储。所以一个Localitygroup个存储维度的概念，而Columnfamily是个逻辑概念，一个Localitygroup可能包含1个或多个Columnfamily。  
+2. mutation Reader 的读写接口中 的参数qualifier是什么？  
+如1中所述，qualifier是Tera中实际的列，或者说列名的意思。  
+3. scan接口描述中在设置区间返回后，做了下面两个add，desc->AddColumnFamily("family21");desc->AddColumn("family22", "qualifier22");是指定scan的列么？如果不指定，可以scan整行么？scan多列之后，如何从result_stream中读某列数据？  
+AddColumnFamily是指定要scan的列族，如果指定就只scan出特定列族，如果不指定，会scan出整行，起一个过滤器的作用。  
+scan多列后，可以使用ResultStream的ToMap接口读取，也可以用Next遍历，找到某列数据。
+4. sdk中有tera.h，有tera_easy.h……这几个不同的头文件分别有什么用？  
+Tera的标准SDK在tera.h中，推荐用户使用，tera_easy.h是一个简化后的sdk，功能有限，一般用户不需要关注。  
+TeraSDK的使用，参见文档 [API使用方法](https://github.com/baidu/tera/wiki/%E4%B8%BB%E8%A6%81API%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95)