ceph/src/jaegertracing/thrift/lib/ocaml/README.md

   1 Thrift OCaml Software Library
   2
   3 License
   4 =======
   5
   6 Licensed to the Apache Software Foundation (ASF) under one
   7 or more contributor license agreements. See the NOTICE file
   8 distributed with this work for additional information
   9 regarding copyright ownership. The ASF licenses this file
  10 to you under the Apache License, Version 2.0 (the
  11 "License"); you may not use this file except in compliance
  12 with the License. You may obtain a copy of the License at
  13
  14   http://www.apache.org/licenses/LICENSE-2.0
  15
  16 Unless required by applicable law or agreed to in writing,
  17 software distributed under the License is distributed on an
  18 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  19 KIND, either express or implied. See the License for the
  20 specific language governing permissions and limitations
  21 under the License.
  22
  23
  24 Library
  25 =======
  26
  27 The library abstract classes, exceptions, and general use functions
  28 are mostly jammed in Thrift.ml (an exception being
  29 TServer).
  30
  31 Generally, classes are used, however they are often put in their own
  32 module along with other relevant types and functions. The classes
  33 often called t, exceptions are called E.
  34
  35 Implementations live in their own files. There is TBinaryProtocol,
  36 TSocket, TThreadedServer, TSimpleServer, and TServerSocket.
  37
  38 A note on making the library: Running make should create native, debug
  39 code libraries, and a toplevel.
  40
  41
  42 Struct format
  43 -------------
  44 Structs are turned into classes. The fields are all option types and
  45 are initially None. Write is a method, but reading is done by a
  46 separate function (since there is no such thing as a static
  47 class). The class type is t and is in a module with the name of the
  48 struct.
  49
  50
  51 enum format
  52 -----------
  53 Enums are put in their own module along with
  54 functions to_i and of_i which convert the ocaml types into ints. For
  55 example:
  56
  57 enum Numberz
  58 {
  59   ONE = 1,
  60   TWO,
  61   THREE,
  62   FIVE = 5,
  63   SIX,
  64   EIGHT = 8
  65 }
  66
  67 ==>
  68
  69 module Numberz =
  70 struct
  71 type t =
  72 | ONE
  73 | TWO
  74 | THREE
  75 | FIVE
  76 | SIX
  77 | EIGHT
  78
  79 let of_i = ...
  80 let to_i = ...
  81 end
  82
  83 typedef format
  84 --------------
  85 Typedef turns into the type declaration:
  86 typedef i64 UserId
  87
  88 ==>
  89
  90 type userid Int64.t
  91
  92 exception format
  93 ----------------
  94 The same as structs except that the module also has an exception type
  95 E of t that is raised/caught.
  96
  97 For example, with an exception Xception,
  98 raise (Xception.E (new Xception.t))
  99 and
 100 try
 101   ...
 102 with Xception.E e -> ...
 103
 104 list format
 105 -----------
 106 Lists are turned into OCaml native lists.
 107
 108 Map/Set formats
 109 ---------------
 110 These are both turned into Hashtbl.t's. Set values are bool.
 111
 112 Services
 113 --------
 114 The client is a class "client" parametrized on input and output
 115 protocols. The processor is a class parametrized on a handler. A
 116 handler is a class inheriting the iface abstract class. Unlike other
 117 implementations, client does not implement iface since iface functions
 118 must take option arguments so as to deal with the case where a client
 119 does not send all the arguments.