Commit 53f5c0ed authored by gerd's avatar gerd

docs


git-svn-id: https://gps.dynxs.de/private/svn/app-plasma/trunk@233 55289a75-7b90-4627-9e07-ffb4263930b2
parent afde0b23
-----------
release
-----------
Last meter software changes:
- Plasma_client: better way to find the coordinator
- plasma utility: -namenode-file
- plasma_utility: Also get namenodes and cluster name from env variable,
or from .plasma
- Plasma_util.fallocate: catch the case fallocate is not supported
Installation:
- add configure script - mainly check whether everything is there in
the right version
- allow to install
- clusterconfig: add config file with paths to executables
Documentation:
- INSTALL, Plasmafs_install
- README
- GPL
- Release documentation, especially what is not yet working
- .x files
- Explanations about the transaction model
- Use of shared memory
- Mapred instructions
- Mapred primer
- External: blog article(s)
Release:
- pack to tar.gz
- create camlcity project page
- GODI package (together with ocamlnet3)
--------------
for mapred demo
--------------
......
# Add here the host names of the machines that are going to be
# task nodes. One host name per line. (You can also make this file
# a symlink to datanode.hosts)
......@@ -18,13 +18,44 @@ DOCS = plasmafs_start.txt \
commands/cmd_plasma_admin.txt \
commands/cmd_nfs3d.txt
html: $(DOCS) plasma_intro.txt odoc/chtml.cmo
IPC = ../ipc
X = $(IPC)/pfs_types.x \
$(IPC)/pfs_nn_fsys.x \
$(IPC)/pfs_nn_coord.x \
$(IPC)/pfs_nn_inodecache.x \
$(IPC)/pfs_nn_dnadmin.x \
$(IPC)/pfs_nn_internal.x \
$(IPC)/pfs_nfs3.x \
$(IPC)/pfs_datanode.x \
$(IPC)/pfs_dn_internal.x \
$(IPC)/pfs_server.x \
$(IPC)/pfs_client.x \
$(IPC)/pmr_task.x
X_TXT = ipc/pfs_types.txt \
ipc/pfs_nn_fsys.txt \
ipc/pfs_nn_coord.txt \
ipc/pfs_nn_inodecache.txt \
ipc/pfs_nn_dnadmin.txt \
ipc/pfs_nn_internal.txt \
ipc/pfs_nfs3.txt \
ipc/pfs_datanode.txt \
ipc/pfs_dn_internal.txt \
ipc/pfs_server.txt \
ipc/pfs_client.txt \
ipc/pmr_task.txt
html: $(DOCS) plasma_intro.txt odoc/chtml.cmo ipc/done
rm -rf html
mkdir -p html
cp *.png style.css html/
ocamldoc -i odoc -g chtml.cmo -d html -stars -css-style style.css \
-t "Plasma Documentation" -intro plasma_intro.txt \
$(LOAD) $(DOCS)
$(LOAD) $(DOCS) $(X_TXT)
ipc/done: $(X)
mkdir -p ipc
odoc/x_to_odoc -d ipc $(X)
touch ipc/done
odoc/chtml.cmo:
cd odoc && $(MAKE)
......
.PHONY: all
all: chtml.cmo
all: chtml.cmo x_to_odoc
chtml.cmo: chtml.ml
ocamlc -I +ocamldoc -c chtml.ml
x_to_odoc: x_to_odoc.ml
ocamlc -o x_to_odoc str.cma x_to_odoc.ml
.PHONY: clean
clean:
rm -f *.cmi *.cmo
rm -f x_to_odoc
.PHONY: CLEAN
CLEAN: clean
......
(* Convert .x files to ocamldoc .txt files. Structured comments
are /** ... */. They must be on lines of their own.
*)
open Printf
let start_re = Str.regexp "^[ \t]*/\\*\\*"
let end_re = Str.regexp "\\*/"
let special_re = Str.regexp "[]{}@[]"
let rec non_space s k =
if k < String.length s then
let c = s.[k] in
if c = ' ' then non_space s (k+1) else Some k
else
None
let convert f_in f_out =
let mode = ref `Code in
let esc s =
Str.global_substitute
special_re
(fun u -> "\\" ^ Str.matched_string u)
s in
let code_buf = Buffer.create 80 in
let output_code s =
Buffer.add_string code_buf (esc s) in
let flush_code() =
let s = Buffer.contents code_buf in
Buffer.clear code_buf;
match non_space s 0 with
| None -> ()
| Some nonspc ->
fprintf f_out "{v %s v}" s in
let output_comment s =
flush_code();
output_string f_out s in
let output_newline () =
if !mode = `Code then
Buffer.add_string code_buf "\n"
else
output_string f_out "\n" in
try
while true do
let line = input_line f_in in
let len = String.length line in
let comment_starts =
if !mode = `Code && Str.string_match start_re line 0 then
Some(String.index line '/')
else
None in
let comment_ends =
if !mode = `Comment || comment_starts <> None then
try Some(Str.search_forward end_re line 0) with Not_found -> None
else
None in
( match comment_starts, comment_ends with
| None, None ->
( match !mode with
| `Code -> output_code line
| `Comment -> output_comment line
)
| Some pos, None ->
output_comment (String.sub line (pos+3) (len - pos - 3))
| None, (Some pos) ->
output_comment (String.sub line 0 pos);
output_code (String.sub line (pos+2) (len - pos - 2))
| (Some spos), (Some epos) ->
output_comment (String.sub line (spos+3) (epos - spos - 3));
output_code (String.sub line (epos+2) (len - epos - 2))
);
if comment_starts <> None then mode := `Comment;
if comment_ends <> None then mode := `Code;
output_newline()
done
with
| End_of_file ->
flush_code()
let main() =
let outdir = ref "." in
let files = ref [] in
Arg.parse
[ "-d", Arg.Set_string outdir, "<dir> Output into this directory" ]
(fun s -> files := !files @ [s])
"usage: x_to_odoc file.x ...";
List.iter
(fun ifile ->
let ofile =
!outdir ^ "/" ^
Filename.chop_extension (Filename.basename ifile) ^ ".txt" in
try
let f_ifile = open_in ifile in
let f_ofile = open_out ofile in
convert f_ifile f_ofile;
close_in f_ifile;
close_out f_ofile;
with
| error ->
Sys.remove ofile;
raise error
)
!files
let () =
main()
......@@ -39,6 +39,22 @@ Client applications can only link with {b plasmasupport} and
Plasma_client
}
{2 PlasmaFS RPC protocol definition}
These are XDR definitions:
- {!Pfs_types}: Types for all RPC definitions
- {!Pfs_nn_fsys}: Filesystem access
- {!Pfs_nn_coord}: Determining the coordinator
- {!Pfs_nn_inodecache}: Inode cache
- {!Pfs_nn_dnadmin}: Administration of the known datanodes
- {!Pfs_nn_internal}: Internal interfaces used between PlasmaFS RPC servers
- {!Pfs_datanode}: Datanode access
- {!Pfs_dn_internal}: Internal interfaces used between PlasmaFS RPC servers
- {!Pfs_nfs3}: NFS version 3
- {!Pfs_server}: All RPC definitions for server context
- {!Pfs_client}: All RPC definitions for client context
{2 PlasmaFS Internal Server Interfaces}
The following interfaces exist only within the server.
......@@ -112,3 +128,9 @@ The following interfaces exist only within the server.
Mapred_rpc_clnt
Mapred_rpc_srv
}
{2 Plasma MapReduce RPC protocol definition}
These are XDR definitions:
- {!Pmr_task}: The RPC definition of the task executor
......@@ -112,7 +112,14 @@ It must be configured as follows:
For each PlasmaFS instance accessing a PostgreSQL server there must be
a buffer for prepared transactions (i.e. normally at least one).
You can change that by setting the parameter [max_prepared_transaction]
in [postgresql.conf] to a positive value.
in [postgresql.conf] to a positive value. Restart PostgreSQL.
Further remarks:
- There is no need to install Ocaml on the cluster nodes. Ocaml executables
are self-containing except that they dynamically link system libraries.
- Of course, the required system libraries must also exist on the
cluster nodes. This is especially libpcre and the PostgreSQL client library
libpq.
The remaining instructions on this page use the scripts in the
[clusterconfig] directory. This is installed together with the other
......@@ -211,6 +218,8 @@ This step creates the PostgreSQL databases on the namenodes:
If the databases already exist, this step will fail. Use the
switch [-drop] to delete databases that were created in error.
The databases have the name [plasma_<inst>].
After initializing the namenodes, it is possible to start the
namenode server with
......
......@@ -14,8 +14,8 @@ program Filesystem {
rvoid abort_transaction(trans_id) = 3;
/* Procedures must usually run inside a transaction. Exceptions:
- get_fsstat
- get_blocksize
.- get_fsstat
.- get_blocksize
*/
/* transaction isolation: only committed changes are visible from
......
/* $Id$ -*- c -*- */
/** Types for the RPC interfaces */
#ifndef PFS_TYPES_X
#define PFS_TYPES_X
/** {2 [longstring]} */
typedef string longstring<>;
/* A string up to 4G length */
/** A string up to 4G length */
/** {2 [longstrings]} */
typedef longstring longstrings<>;
/* An array of longstrings */
/** An array of longstrings */
/** {2 [longstring_opt]} */
typedef longstring *longstring_opt;
/* A longstring option */
/** A longstring option */
/** {2 [hypers]} */
typedef hyper hypers<>;
/* An array of hypers */
/** An array of hypers */
/** {2 [trans_id]} */
typedef hyper trans_id;
/* transaction IDs can be used to run several transactions over the same
TCP connection
/** transaction IDs can be used to run several transactions over the same
TCP connection
*/
/** {2 [ug]} */
struct ug {
longstring user;
longstring group;
};
/** Users and groups are given by name */
/** {2 [time] } */
struct time {
hyper tsecs; /* Seconds since the epoch... */
int tnsecs; /* plus these nanoseconds */
};
/* tsecs and tnsecs must be non-negative; tnsecs < 1E9. In update_inodeinfo
a negative tsecs is interpreted as "set the time to the current server
time"
/** [tsecs] and [tnsecs] must be non-negative; [tnsecs < 1E9]. In
the filesystem procedure [update_inodeinfo]
a negative [tsecs] is interpreted as "set the time to the current server
time"
*/
/** {2 [time_opt]} */
typedef time *time_opt;
/** an optional time struct */
/** {2 [ftype_enum]} */
enum ftype_enum {
FTYPE_REGULAR = 0,
FTYPE_DIRECTORY = 1,
FTYPE_SYMLINK = 2
};
/** File types */
/** {2 [ftype]} */
union ftype switch(ftype_enum d) {
case FTYPE_REGULAR:
......@@ -49,6 +74,7 @@ union ftype switch(ftype_enum d) {
default:
void;
};
/** File types as union */
struct blockinfo {
hyper index; /* block index */
......
......@@ -18,8 +18,8 @@ program Mapred_task {
*/
/* TODO:
- get_req_id : void -> int
- status : int -> bool (running/not running)
.- get_req_id : void -> int
.- status : int -> bool (running/not running)
*/
void kill(int) = 2;
......@@ -30,8 +30,8 @@ program Mapred_task {
void configure(hyper, hyper) = 4;
/* configure(shm_low, shm_high):
- shm_low: low-water mark for shm
- shm_high: high-water mark for shm
.- shm_low: low-water mark for shm
.- shm_high: high-water mark for shm
*/
} = 1;
} = 0x80013001;
......
......@@ -117,6 +117,15 @@ if $(not $(defined OCAMLRPCGEN))
OCAMLRPCGEN = ocamlrpcgen
export
public.InterfaceDoc(name, files) =
protected.mlifiles = $(filter-exists $(addsuffix .mli, $(files)))
$(name).idoc: $(mlifiles)
ocamlfind ocamldoc -dump $(name).idoc -stars \
$(PREFIXED_OCAMLINCLUDES) -package "$(OCAMLPACKS)" \
$(mlifiles)
return $(name).idoc
########################################################################
# Subdirectories.
# You may want to include some subdirectories in this project.
......
......@@ -85,6 +85,8 @@ OCAML_LIBS[] =
.DEFAULT: $(OCamlProgram mr_test, $(FILES) mr_test)
.DEFAULT: $(InterfaceDoc $(LIB), $(FILES))
################################################
# Build an OCaml program
#
......@@ -103,5 +105,5 @@ OCAML_LIBS[] =
clean:
rm -f $(RPCAPI)
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.run *.opt *.annot
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.run *.opt *.annot *.idoc
rm -f mr_test
......@@ -44,5 +44,7 @@ OCAMLINCLUDES += ../plasmasupport ../pfs_support
.DEFAULT: $(OCamlLibrary $(LIB), $(FILES))
.DEFAULT: $(InterfaceDoc $(LIB), $(FILES))
clean:
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot *.idoc
......@@ -26,3 +26,22 @@ end
val extract_dn_config : Netplex_types.config_file -> dn_config
(** Config section must look like (see {!Dn_config.dn_config}
for explanations):
{[
netplex {
...
datanode {
clustername = "<name>";
directory = "<data_dir>";
blocksize = <blocksize>; (* int *)
io_processes = <p>; (* int *)
shm_queue_length = <q>; (* int *)
sync_period = <s>; (* float *)
};
...
}
]}
*)
......@@ -55,5 +55,7 @@ OCAMLINCLUDES += ../bitv ../plasmasupport ../pfs_support ../postgresql
.DEFAULT: $(OCamlLibrary $(LIB), $(FILES))
.DEFAULT: $(InterfaceDoc $(LIB), $(FILES))
clean:
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot *.idoc
......@@ -40,24 +40,25 @@ end
val extract_node_config : Netplex_types.config_file -> nn_node_config
(** Config section must look like:
(** Config section must look like (see {!Nn_config.nn_node_config}
for explanations):
{[
netplex {
...
namenodes {
clustername = "cluster1";
node { addr = "hostname:port" }
node { addr = "hostname:port" }
clustername = "cluster1"; (* required *)
node { addr = "hostname:port" };
node { addr = "hostname:port" };
...
hostname = "hostname"; (* optional *)
timeout = 60.0; (* optional *)
alive_min = 1; (* optional *)
alive_min_startup = 1; (* optional *)
elect_timeout 300.0; (* optional *)
rank = 0; (* mandatory *)
inodecache { port = <port> };
rank = "0"; (* mandatory *)
replication = 3; (* optional *)
inodecache { port = <port> };
}
datanodes {
node { addr = "hostname:port" }
......@@ -70,20 +71,22 @@ val extract_node_config : Netplex_types.config_file -> nn_node_config
}
]}
Instead of describing the nodes directly in the config file, one
can also point to external file:
The parameter [rank] can also be given by running a script that
outputs the rank to stdout. This script must be given as
parameter [rank_script].
Instead of describing the nodes directly in the config file
using [node] subsections, one can also point to external file:
{[ node_list = "filename";
{[
node_list = "filename";
port = <default_port>;
]}
inodecache: must be running on all namenodes on the given port.
The client gets only the inodecache running on the coordinator.
These two parameters can replace both the [node] subsections for
[namenodes] and for [datanodes]. The external file enumerates the
hosts, one hostname a line (with shell-style comments).
*)
(* TODO: It is not satisfactory that the config file is not identical
on all namenodes. Especially [rank] must be distinct everywhere.
*)
val bmaprowsize : int
(** block map row size - how many bits are in one row of the block map.
......
......@@ -15,7 +15,7 @@ open Nn_datastores
exception Unavailable
(** Raised if the news feed is not yet available (try again later),
and the {wait] option is not set.
and the [wait] option is not set.
*)
val force : unit -> unit
......
......@@ -239,6 +239,8 @@ class type inode_view_t =
object
inherit view_t
(** {2 inode access} *)
method inode_get_e : id:int64 ->
Pfs_rpcapi_aux.inodeinfo option Uq_engines.engine
method inode_alloc_e : Pfs_rpcapi_aux.inodeinfo ->
......@@ -287,6 +289,8 @@ object
unit
(** This update of mtime/ctime is lock-free *)
(** {2 Filenames} *)
(** For simplicity, the filename access is also defined here. Inodes and
filenames interact with each other to some extent, and it is important
that inode and filename operations are executed in the right order
......@@ -331,6 +335,11 @@ object
end
(** The following classes are used as follows: First, a [shared_state]
is created. This object is passed on as arguments to the view
objects. The views, if all connected with the same [shared_state],
can be committed in one go (in {!Nn_commit}).
*)
class shared_state : Unixqueue.event_system ->
nn_node_config ->
......@@ -345,3 +354,4 @@ class bm_view : shared_state_t -> bm_view_t
class inode_view : shared_state_t -> inode_view_t
val encap_time : float -> Pfs_rpcapi_aux.time
(** Turn the time (as seconds since epoch) into the RPC version *)
......@@ -66,6 +66,8 @@ OCAML_LIBS += ../plasmasupport/plasmasupport ../plasmaclient/plasmaclient
.DEFAULT: $(OCamlLibrary $(LIB), $(FILES))
.DEFAULT: $(InterfaceDoc $(LIB), $(FILES))
.DEFAULT: $(OCamlProgram nfs3d, $(FILES) nfs3d)
################################################
......@@ -86,5 +88,5 @@ OCAML_LIBS += ../plasmasupport/plasmasupport ../plasmaclient/plasmaclient
clean:
rm -f $(RPCAPI)
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot *.opt *.run
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot *.opt *.run *.idoc
rm -f nfs3d
......@@ -60,6 +60,8 @@ LIB = plasmaclient
.DEFAULT: $(OCamlLibrary $(LIB), $(FILES))
.DEFAULT: $(InterfaceDoc $(LIB), $(FILES))
################################################
# Build an OCaml program
#
......@@ -85,5 +87,5 @@ OCAML_LIBS[] =
clean:
rm -f $(RPCAPI)
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.run *.opt
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.run *.opt *.annot *.idoc
rm -f plasma
......@@ -6,6 +6,8 @@
- rename
*)
(** Client access to the Plasma Filesystem *)
open Plasma_rpcapi_aux
type plasma_cluster
......@@ -83,24 +85,6 @@ val configure_shm_manager : plasma_cluster -> Plasma_shm.shm_manager -> unit
val shm_manager : plasma_cluster -> Plasma_shm.shm_manager
(** Returns the current manager *)
(** {2 Transactions} *)
(** If not run within a transaction block, the commands will create a
transaction and commit it ("autocommit").
*)
val start_e : plasma_cluster -> plasma_trans Uq_engines.engine
val start : plasma_cluster -> plasma_trans
(** Starts a transaction *)
val commit_e : plasma_trans -> unit Uq_engines.engine
val commit : plasma_trans -> unit
(** Commits a transaction *)
val abort_e : plasma_trans -> unit Uq_engines.engine
val abort : plasma_trans -> unit
(** Aborts a transaction *)
val blocksize_e : plasma_cluster -> int Uq_engines.engine
val blocksize : plasma_cluster -> int
(** Returns the blocksize *)
......@@ -115,6 +99,21 @@ val local_identities : plasma_cluster -> string list
(for [configure_pref_nodes])
*)
(** {2 Transactions} *)
val start_e : plasma_cluster -> plasma_trans Uq_engines.engine
val start : plasma_cluster -> plasma_trans
(** Starts a transaction *)
val commit_e : plasma_trans -> unit Uq_engines.engine
val commit : plasma_trans -> unit
(** Commits a transaction *)
val abort_e : plasma_trans -> unit Uq_engines.engine
val abort : plasma_trans -> unit
(** Aborts a transaction *)
val cluster : plasma_trans -> plasma_cluster
(** the cluster to which a transaction belongs *)
......
......@@ -26,6 +26,8 @@ LIB = plasmasupport
.DEFAULT: $(OCamlLibrary $(LIB), $(FILES))
.DEFAULT: $(InterfaceDoc $(LIB), $(FILES))
clean:
rm -f $(RPCAPI)
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot
rm -f *.a *.cmx *.cmxa *.o *.cmo *.cma *.cmi *.annot *.idoc
(* $Id$ *)
(** Random numbers *)
val random_bytes : int -> string
(** Returns a string with n random bytes *)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment