Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Convert to Markdown

Conflicts:

	eep-0005.md
	eep-0006.md
	eep-0007.md
	eep-0008.md
	eep-0009.md
	eep-0010.md
	eep-0011.md
	eep-0012.md
  • Loading branch information...
commit 716d4a94fd3c27a6a355761ec8cf0daa2c458f80 1 parent 6150b5a
authored January 14, 2010 RaimoNiskanen committed April 06, 2010
41  eeps/eep-0005.md
Source Rendered
... ...
@@ -1,17 +1,18 @@
1  
-EEP: 5
2  
-Title: More Versatile Encapsulation with export_to
3  
-Version: $Revision$
4  
-Last-Modified: $Date$
5  
-Author: Per Gustafsson
6  
-Status: Draft
7  
-Type: Standards Track
8  
-Content-Type: text/x-rst
9  
-Created: 10-Aug-2007
10  
-Erlang-Version: R12B-0
11  
-Post-History: 
  1
+EEP 5: More Versatile Encapsulation with export_to
  2
+====
  3
+
  4
+    Author: Per Gustafsson
  5
+    Status: Draft
  6
+    Type: Standards Track
  7
+    Content-Type: text/x-markdown
  8
+    Created: 10-Aug-2007
  9
+    Erlang-Version: R12B-0
  10
+    Post-History: 
  11
+
  12
+====
12 13
 
13 14
 Abstract
14  
-========
  15
+--------
15 16
 
16 17
 This EEP describes a new directive called export_to which allows a
17 18
 module to specify exactly which other modules that can call a function
@@ -22,7 +23,7 @@ his code should be used.
22 23
 This is an idea originally proposed by Richard O'Keefe. 
23 24
 
24 25
 Specification
25  
-=============
  26
+-------------
26 27
 
27 28
 This is the syntax for the export_to directive:
28 29
 
@@ -31,8 +32,8 @@ This is the syntax for the export_to directive:
31 32
 where `f` is the name of a function of arity `a` and `m` is a
32 33
 module. (Perhaps we should allow a list of modules)
33 34
 
34  
-This means that the function f/a can be called from the module
35  
-m. Whether the call is a static call, dynamic call or an apply should
  35
+This means that the function `f/a` can be called from the module
  36
+`m`. Whether the call is a static call, dynamic call or an apply should
36 37
 not matter.
37 38
 
38 39
 In addition these functions should act as exported functions to the
@@ -40,7 +41,7 @@ rest of the world i.e. calls to these functions should always be to
40 41
 the latest version of the function.
41 42
 
42 43
 Motivation
43  
-==========
  44
+----------
44 45
 
45 46
 The module in Erlang have several roles. It is the unit of compilation
46 47
 and code reloading. It is also the unit of encapsulation, because the
@@ -67,14 +68,14 @@ the export directive, but to be an alternative in the case when the
67 68
 programmer knows all possible collaborators.
68 69
 
69 70
 Rationale 
70  
-=========
  71
+---------
71 72
 
72 73
 There are some choices in designing the export_to syntax for example
73 74
 should m be allowed to be a list of modules or should we have an
74 75
 export_to list where each entry is a module, function/arity pair. One
75 76
 reason to use the suggested syntax is that it reads pretty easily as:
76 77
 
77  
-export to module m this list of functions [f/a]
  78
+export to module `m` this list of functions `[f/a]`
78 79
 
79 80
 Another issue is whether we should have some syntactic sugar for
80 81
 specifying common export patterns e.g. exporting a set of functions to
@@ -89,14 +90,14 @@ creating such extensions without having to change the Erlang runtime.
89 90
   .. Other languages that have something like this? 
90 91
 
91 92
 Backwards Compatibility
92  
-=======================
  93
+-----------------------
93 94
 
94 95
 Adding an export_to directive should be totally backwards
95 96
 compatible. Since writing such a directive now causes a syntax error
96 97
 since it is not a legal attribute.
97 98
 
98 99
 Implementation
99  
-==============
  100
+--------------
100 101
 
101 102
 This feature has not been implemented yet, but here are some goals
102 103
 that we think the implementation should fulfill:
35  eeps/eep-0006.md
Source Rendered
... ...
@@ -1,28 +1,29 @@
1  
-EEP: 6
2  
-Title: New BIFs for tuple and binary sizes
3  
-Version: $Revision$
4  
-Last-Modified: $Date$
5  
-Author: Bjorn Gustavsson
6  
-Status: Draft
7  
-Type: Standards Track
8  
-Content-Type: text/x-rst
9  
-Created: 10-Aug-2007
10  
-Erlang-Version: R12B-0
11  
-Post-History: 
  1
+EEP 6: New BIFs for tuple and binary sizes
  2
+====
  3
+
  4
+    Author: Bjorn Gustavsson
  5
+    Status: Draft
  6
+    Type: Standards Track
  7
+    Content-Type: text/x-markdown
  8
+    Created: 10-Aug-2007
  9
+    Erlang-Version: R12B-0
  10
+    Post-History: 
  11
+
  12
+====
12 13
 
13 14
 Abstract
14  
-========
  15
+--------
15 16
 
16 17
 This EEP describes the two new guards BIFs ``tuple_size/1`` and ``byte_size/1``
17 18
 as a prefered alternative to the ``size/1`` BIF.
18 19
 
19 20
 Specifications
20  
-==============
  21
+--------------
21 22
 
22 23
 ``byte_size/1::bitstring() -> integer()``
23 24
 
24 25
 Returns the number of bytes needed to store the entire *bitstring*
25  
-(see http://www.erlang.org/eeps/eep-0004.html). This BIF will return
  26
+(see <http://github.com/KennethL/EEP/blob/master/eep-0004.md>). This BIF will return
26 27
 the same value as ``(bit_size(Bin)+7) div 8`` (that is, the number
27 28
 of bytes will be rounded up if number of bits is not evenly divisible by 8).
28 29
 This BIF is allowed in guards.
@@ -33,7 +34,7 @@ Returns the size of a tuple. This BIF will fail if passed anything
33 34
 that is not a tuple. This BIF is allowed in guards.
34 35
 
35 36
 Rationale
36  
-=========
  37
+---------
37 38
 
38 39
 The ``size/1`` BIF accepts either a binary or a tuple, and returns
39 40
 either the size of binary in bytes or the size of the tuple.
@@ -54,12 +55,12 @@ and the correct expression ``(bit_size(B)+7) div 8`` is not immediately
54 55
 obvious.
55 56
 
56 57
 Implementation
57  
-==============
  58
+--------------
58 59
 
59 60
 The implementation is trivial.
60 61
 
61 62
 Backwards Compatibility
62  
-=======================
  63
+-----------------------
63 64
 
64 65
 Code containing local functions named ``tuple_size/1`` or ``byte_size/1`` need
65 66
 to be changed.
480  eeps/eep-0007.md
Source Rendered
... ...
@@ -1,18 +1,18 @@
1  
-EEP: 7
2  
-Title: Foreign Function Interface (FFI)
3  
-Version: $Revision$
4  
-Last-Modified: $Date$
5  
-Author: Alceste Scalas [alceste(at)crs4(dot)it]
6  
-Status: Draft
7  
-Type: Standards Track
8  
-Content-Type: text/x-rst
9  
-Created: 3-Sep-2007
10  
-Erlang-Version: R12B
11  
-Post-History:
  1
+EEP 7: Foreign Function Interface (FFI)
  2
+====
12 3
 
  4
+    Author: Alceste Scalas [alceste(at)crs4(dot)it]
  5
+    Status: Draft
  6
+    Type: Standards Track
  7
+    Content-Type: text/x-markdown; charset=utf-8
  8
+    Created: 3-Sep-2007
  9
+    Erlang-Version: R12B
  10
+    Post-History:
  11
+
  12
+====
13 13
 
14 14
 Abstract
15  
-========
  15
+--------
16 16
 
17 17
 This EEP describes a Foreign Function Interface (FFI) for Erlang/OTP,
18 18
 that allows to easily perform direct calls of external C functions.
@@ -30,7 +30,7 @@ information.
30 30
 
31 31
 
32 32
 Motivation
33  
-==========
  33
+----------
34 34
 
35 35
 The current Erlang extension mechanisms can be divided in two main
36 36
 categories:
@@ -46,8 +46,8 @@ the Erlang driver interface implies the development of relevant
46 46
 amounts of glue code, mostly because the communication between Erlang
47 47
 and C always requires data parsing and (de)serialization.  Several
48 48
 tools have been created in order to autogenerate (at least part of)
49  
-that glue: from the (now unmaintained) IG driver generation tool [1]_
50  
-to the newer Erlang Driver Toolkit (EDTK) [2]_ and Dryverl [3]_.
  49
+that glue: from the (now unmaintained) [IG driver generation tool] [1]
  50
+to the newer [Erlang Driver Toolkit (EDTK)] [2] and [Dryverl] [3].
51 51
 
52 52
 But, even with the help of these tools, developing an Erlang driver is
53 53
 a difficult and time-consuming task (especially when interfacing
@@ -68,7 +68,7 @@ extend the Erlang capabilities and open new usage scenarios.
68 68
 
69 69
 
70 70
 Rationale
71  
-=========
  71
+---------
72 72
 
73 73
 This EEP proposes a Foreign Function Interface (FFI) extension that
74 74
 would allow to easily perform direct C function calls.  This concept
@@ -76,10 +76,10 @@ is implemented in almost every language, with two main (non-exclusive)
76 76
 approaches:
77 77
 
78 78
 1. automatic type conversions between the host and the foreign
79  
-   language (examples: Python [7]_, Haskell [8]_);
  79
+   language (examples: [Python] [7], [Haskell] [8]);
80 80
 
81 81
 2. documented C interface for handling host language types from the
82  
-   foreign language (examples: Java [9]_, Python [10]_ [11]_).
  82
+   foreign language (examples: [Java] [9], [Python] [10] [11][]).
83 83
 
84 84
 This EEP follows the first approach, but (when possible) also reuses
85 85
 part of the existing C Driver API (and, thus, allows to manage
@@ -99,7 +99,7 @@ efficient) way to call C code from Erlang.
99 99
 
100 100
 
101 101
 Overview
102  
-========
  102
+--------
103 103
 
104 104
 In order to call a C function, the FFI needs a port opened towards the
105 105
 required C code.  Thus, with the current driver loading mechanism, a
@@ -129,8 +129,7 @@ functions, and perform calls either through the low-level or the
129 129
 high-level APIs.
130 130
 
131 131
 
132  
-Low-level API
133  
--------------
  132
+### Low-level API ###
134 133
 
135 134
 The low-level FFI methods are denoted by the ``raw_`` prefix.  The
136 135
 main function is the `ffi:raw_call/3`_ BIF, that performs a direct C
@@ -152,8 +151,7 @@ These BIFs are `ffi:raw_buffer_to_binary/2`_ and
152 151
 `ffi:raw_cstring_to_binary/1`_.
153 152
 
154 153
 
155  
-High-level API
156  
---------------
  154
+### High-level API ###
157 155
 
158 156
 The high-level interface is built upon the low-level one.  It
159 157
 introduces the concept of type-tagged values: any value passed to or
@@ -179,8 +177,7 @@ low-level BIFs).  Type-tagged values can also be checked with
179 177
 each FFI type can be examined with `ffi:min/1`_ and `ffi:max/1`_.
180 178
 
181 179
 
182  
-Utility macros
183  
---------------
  180
+### Utility macros ###
184 181
 
185 182
 The FFI defines a series of utility macros in the `ffi_hardcodes.hrl`_
186 183
 header file, that could be used for binary matching of C buffers and
@@ -188,46 +185,41 @@ structures.
188 185
 
189 186
 
190 187
 Specifications
191  
-==============
  188
+--------------
  189
+
  190
+### Types ###
192 191
 
193  
-Types
194  
------
195 192
 
196  
-c_func_name()
197  
-'''''''''''''
  193
+#### c_func_name()
198 194
 
199 195
     `c_func_name() = atom() | string()`
200 196
 
201 197
 Name of a C function.
202 198
 
203 199
 
204  
-type_tag()
205  
-''''''''''
  200
+#### type_tag()
206 201
 
207 202
     `type_tag() = atom()`
208 203
 
209 204
 Valid FFI type atom.  For the list of allowed values, see the
210  
-Appendix_.
  205
+Appendix.
211 206
 
212 207
 
213  
-tagged_value()
214  
-''''''''''''''
  208
+##### tagged_value()
215 209
 
216 210
     `tagged_value() = tuple(type_tag(), term())`
217 211
 
218 212
 Type-tagged value used for FFI calls.
219 213
 
220 214
 
221  
-tagged_func_name()
222  
-''''''''''''''''''
  215
+#### tagged_func_name()
223 216
 
224 217
     `tagged_func_name() = tuple(type_tag(), c_func_name())`
225 218
 
226 219
 C function name with return type.
227 220
 
228 221
 
229  
-func_index()
230  
-''''''''''''
  222
+#### func_index()
231 223
 
232 224
     `func_index() = integer()`
233 225
 
@@ -235,16 +227,14 @@ Function position on the list of preloads given to
235 227
 `erl_ddll:load_library/3`_.
236 228
 
237 229
 
238  
-tagged_func_index()
239  
-'''''''''''''''''''
  230
+#### tagged_func_index()
240 231
 
241 232
     `tagged_func_index() = tuple(type_tag(), func_index())`
242 233
 
243 234
 C function index with return type.
244 235
 
245 236
 
246  
-signature()
247  
-'''''''''''
  237
+#### signature()
248 238
 
249 239
     `signature() = tuple(type_tag(), ...)`
250 240
 
@@ -252,10 +242,8 @@ Signature of a C function: return type followed by arguments types (if
252 242
 any).
253 243
 
254 244
 
255  
-erl_ddll:load_library/3
256  
------------------------
  245
+### erl_ddll:load_library/3 ###
257 246
 
258  
-::
259 247
 
260 248
     erl_ddll:load_library(Path, Name,
261 249
                           OptionsList) -> ok | {error, ErrorDesc}
@@ -277,28 +265,26 @@ loading the library, this BIF will behave like erl_ddll:load/2.  The
277 265
 function parameters are also the same of erl_ddll:load/2, with the
278 266
 following addition:
279 267
 
280  
-    **OptionList**
281  
-        A list of options for library/driver loading.  The supported
282  
-        options are:
283  
-
284  
-            **{preload, PreloadList}**
285  
-                Preload the given list of functions, and prepare their
286  
-                call structures.  Each PreloadList element is a tuple
287  
-                in the form:
  268
+**OptionList** is a list of options for library/driver loading.
  269
+The supported options are:
288 270
 
289  
-                    tuple(`c_func_name()`_, `signature()`_)
  271
+ - **`{preload, PreloadList}`**
  272
+   Preload the given list of functions, and prepare their
  273
+   call structures.  Each PreloadList element is a tuple
  274
+   in the form:
  275
+   tuple(`c_func_name()`_, `signature()`_)
290 276
 
291  
-                i.e. the function name followed by its return and
292  
-                arguments types.
  277
+   i.e. the function name followed by its return and
  278
+   arguments types.
293 279
 
294 280
 The function return values are the same of erl_ddll:load/2.
295 281
 
296 282
 Once a library has been loaded, it is possible to use
297  
-erlang:open_port/2 to get a port.  That port could *always* be used
  283
+`erlang:open_port/2` to get a port.  That port could *always* be used
298 284
 with `ffi:call/3`_, `ffi:raw_call/3`_ or `ffi:raw_call/2`_.  However,
299 285
 if the loaded library does *not* contain a proper ``ErlDrvEntry``
300 286
 structure and a driver init function, the port will **not** be usable
301  
-with erlang:port_command/2, erlang:port_control/3 etc.
  287
+with `erlang:port_command/2`, `erlang:port_control/3` etc.
302 288
 
303 289
 The following example loads the C standard library and preloads some
304 290
 functions: ::
@@ -311,10 +297,7 @@ functions: ::
311 297
                                   {free, {void, nonnull}}]}]).
312 298
 
313 299
 
314  
-erl_ddll:load_library/2
315  
------------------------
316  
-
317  
-::
  300
+### erl_ddll:load_library/2 ###
318 301
 
319 302
     erl_ddll:load_library(Path, Name)
320 303
 
@@ -322,10 +305,7 @@ Utility function that calls `erl_ddll:load_library/3`_ with an empty
322 305
 OptionsList.
323 306
 
324 307
 
325  
-erlang:open_port/1
326  
-------------------
327  
-
328  
-::
  308
+### erlang:open_port/1 ###
329 309
 
330 310
     erlang:open_port(Library)
331 311
 
@@ -336,20 +316,17 @@ Types:
336 316
 Open a port towards the specified shared library, possibly loaded with
337 317
 `erl_ddll:load_library/3`_.  Calling this function is equivalent to:
338 318
 
339  
-::
340  
-
341 319
     erlang:open_port({spawn, Library}, [binary])
342 320
 
343 321
 
344  
-erl_ddll:info/2
345  
----------------
  322
+### erl_ddll:info/2 ###
346 323
 
347 324
 This EEP proposes a new parameter for the erl_ddll:info/2 BIF: the
348 325
 'preloads' atom.  It allows to retrieve information about FFI preloads
349 326
 for the given library.
350 327
 
351 328
 The preload information is a list of proplists, one for each preloaded
352  
-function.  Each proplist, in turn, has the following format: ::
  329
+function.  Each proplist, in turn, has the following format: 
353 330
 
354 331
     [ { index,     integer()   },     % Position in the preload list
355 332
       { name,      string()    },     % Function name
@@ -357,13 +334,10 @@ function.  Each proplist, in turn, has the following format: ::
357 334
       { signature, signature() } ]    % Function signature 
358 335
      
359 336
 This information would be made available also through erl_ddll:info/0
360  
-and erl_ddll:info/1.
  337
+and `erl_ddll:info/1`.
361 338
 
362 339
 
363  
-ffi:raw_call/3
364  
---------------
365  
-
366  
-::
  340
+### ffi:raw_call/3 ###
367 341
 
368 342
     ffi:raw_call(Port, CallArgs, Signature) -> term()
369 343
 
@@ -381,22 +355,25 @@ Call the specified C function.
381 355
 
382 356
 This BIF accepts the following parameters:
383 357
 
384  
-    **Port**
385  
-        A port opened towards the required driver/library.
  358
+- **Port**
  359
+    
  360
+    A port opened towards the required driver/library.
386 361
 
387  
-    **CallArgs**
388  
-        A tuple with the function name (atom or string) followed by
389  
-        its arguments (if any).
  362
+- **CallArgs**
  363
+    
  364
+    A tuple with the function name (atom or string) followed by
  365
+    its arguments (if any).
390 366
 
391  
-    **Signature**
392  
-        Function signature
  367
+- **Signature**
  368
+  
  369
+    Function signature.
393 370
 
394 371
 This BIF returns the return value of the C function being called (or
395 372
 'void' if the return type is void).  It automatically converts Erlang
396 373
 terms to/from C values.  The supported C types and conversions are
397  
-reported in the Appendix_.
  374
+reported in the Appendix.
398 375
 
399  
-The following example calls the malloc() and free() functions from the
  376
+The following example calls the `malloc()` and `free()` functions from the
400 377
 standard C library (it should work with any Erlang linked-in driver): ::
401 378
 
402 379
     Pointer = ffi:raw_call(Port, {malloc, 1024}, {pointer, size_t}),
@@ -407,10 +384,7 @@ affect the Erlang VM, possibly making it crash.  Use this BIF with
407 384
 extreme care.
408 385
 
409 386
 
410  
-ffi:raw_call/2
411  
---------------
412  
-
413  
-::
  387
+### ffi:raw_call/2 ###
414 388
 
415 389
     ffi:raw_call(Port, OptimizedCall) -> term()
416 390
 
@@ -429,21 +403,22 @@ Call a function preloaded with the 'preload' option of
429 403
 
430 404
 This BIF accepts the following parameters:
431 405
 
432  
-    **Port**
433  
-        A port opened towards the required driver/library (that
434  
-        **must** have been loaded with `erl_ddll:load_library/3`_).
  406
+- **Port**
  407
+
  408
+    A port opened towards the required driver/library (that
  409
+    **must** have been loaded with `erl_ddll:load_library/3`_).
435 410
 
436  
-    **OptimizedCall**
437  
-        A tuple with the function index (i.e. its position in
438  
-        the preload list) followed by its arguments (if any).
  411
+- **OptimizedCall**
  412
+    A tuple with the function index (i.e. its position in
  413
+    the preload list) followed by its arguments (if any).
439 414
 
440 415
 This BIF returns the return value of the C function being called (or
441 416
 'void' if the return type is void).  It automatically converts Erlang
442 417
 terms to/from C values.  The supported C types and conversions are
443  
-reported in the Appendix_.
  418
+reported in the Appendix.
444 419
 
445  
-The following example calls malloc() and free(), after they have been
446  
-preloaded with the code sample shown in `erl_ddll:load_library/3`_: ::
  420
+The following example calls `malloc()` and `free()`, after they have been
  421
+preloaded with the code sample shown in `erl_ddll:load_library/3`:
447 422
 
448 423
     Port = open_port({spawn, "libc"}, [binary]),
449 424
     Pointer = ffi:raw_call(Port, {3, 1024}),
@@ -454,10 +429,7 @@ affect the Erlang VM, possibly making it crash.  Use this BIF with
454 429
 extreme care.
455 430
 
456 431
 
457  
-ffi:raw_buffer_to_binary/2
458  
---------------------------
459  
-
460  
-::
  432
+### ffi:raw_buffer_to_binary/2 ###
461 433
 
462 434
     ffi:raw_buffer_to_binary(Pointer, Size) -> binary()
463 435
 
@@ -474,10 +446,7 @@ pointer (represented by an integer, possibly returned by a FFI call).
474 446
 Erlang VM to crash.  Use with extreme care.
475 447
 
476 448
 
477  
-ffi:raw_cstring_to_binary/1
478  
----------------------------
479  
-
480  
-::
  449
+### ffi:raw_cstring_to_binary/1 ###
481 450
 
482 451
     ffi:raw_cstring_to_binary(CString) -> binary()
483 452
 
@@ -493,10 +462,7 @@ binary will include the trailing 0.
493 462
 VM to crash.  Use with extreme care.
494 463
 
495 464
 
496  
-ffi:call/3
497  
-----------
498  
-
499  
-::
  465
+### ffi:call/3 ###
500 466
 
501 467
     call(Port, CFunc, Args) -> RetVal
502 468
 
@@ -525,7 +491,7 @@ return type).
525 491
 
526 492
 As an example, the following ``malloc()`` calls are all valid and
527 493
 equivalent when executed after the code sample shown in
528  
-`erl_ddll:load_library/3`_: ::
  494
+`erl_ddll:load_library/3`_:
529 495
 
530 496
     %% Use function name, but require preloads for return type
531 497
     {nonnull, Ptr1} = ffi:call(Port, "malloc", [{size_t, 1024}]),
@@ -544,10 +510,7 @@ affect the Erlang VM, possibly making it crash.  Use this BIF with
544 510
 extreme care.
545 511
 
546 512
 
547  
-ffi:buffer_to_binary/2
548  
-----------------------
549  
-
550  
-::
  513
+### ffi:buffer_to_binary/2 ###
551 514
 
552 515
     ffi:buffer_to_binary(TaggedNonNull, Size) -> binary()
553 516
 
@@ -564,10 +527,7 @@ pointer.
564 527
 Erlang VM to crash.  Use with extreme care.
565 528
 
566 529
 
567  
-ffi:cstring_to_binary/1
568  
------------------------
569  
-
570  
-::
  530
+### ffi:cstring_to_binary/1 ###
571 531
 
572 532
     ffi:cstring_to_binary(TaggedCString) -> binary()
573 533
 
@@ -581,10 +541,7 @@ Return a binary with a copy of the given NULL-terminated C string.
581 541
 Erlang VM to crash.  Use with extreme care.
582 542
 
583 543
 
584  
-ffi:sizeof/1
585  
-------------
586  
-
587  
-::
  544
+### ffi:sizeof/1 ###
588 545
 
589 546
     ffi:sizeof(TypeTag) -> integer()
590 547
 
@@ -596,10 +553,7 @@ Return the size (in bytes) of the given FFI type, on the current
596 553
 platform.
597 554
 
598 555
 
599  
-ffi:check/1
600  
------------
601  
-
602  
-::
  556
+### ffi:check/1 ###
603 557
 
604 558
     ffi:check(TaggedValue) -> true | false
605 559
 
@@ -612,10 +566,7 @@ consistent (i.e. it falls in the allowed range for its type, on the
612 566
 current platform).  Otherwise, returns 'false'.
613 567
 
614 568
 
615  
-ffi:min/1
616  
----------
617  
-
618  
-::
  569
+### ffi:min/1 ###
619 570
 
620 571
     ffi:min(TypeTag) -> integer()
621 572
 
@@ -627,9 +578,7 @@ Return the minimum value allowed for the given FFI type, on the
627 578
 current platform.
628 579
 
629 580
 
630  
-ffi:max/1
631  
----------
632  
-::
  581
+### ffi:max/1 ###
633 582
 
634 583
     ffi:max(TypeTag) -> integer()
635 584
 
@@ -641,35 +590,34 @@ Return the maximum value allowed for the given FFI type, on the
641 590
 current platform.
642 591
 
643 592
 
644  
-ffi_hardcodes.hrl
645  
------------------
  593
+### ffi_hardcodes.hrl ###
646 594
 
647 595
 The `ffi_hardcodes.hrl` file is part of the Erlang ffi library.  It
648 596
 defines a set of macros for handling FFI types sizes, and for easy
649 597
 binary matching on C buffers and structures:
650 598
 
651  
-    **FFI_HARDCODED_<TYPE>**
  599
+- **FFI_HARDCODED_<TYPE>**
652 600
 
653  
-        An Erlang bit-syntax snippet (Size/TypeSpecifier) that could
654  
-        be used to match the given FFI type inside a binary (possibly
655  
-        obtained from a C buffer).  For example, the following binary
656  
-        matching ::
  601
+    An Erlang bit-syntax snippet (Size/TypeSpecifier) that could
  602
+    be used to match the given FFI type inside a binary (possibly
  603
+    obtained from a C buffer).  For example, the following binary
  604
+    matching:
657 605
         
658  
-            <<ULong:?FFI_HARDCODED_ULONG, _Rest/binary>> = Binary
  606
+        <<ULong:?FFI_HARDCODED_ULONG, _Rest/binary>> = Binary
659 607
 
660  
-        on x86-64 will expand to: ::
  608
+    on x86-64 will expand to:
661 609
 
662  
-            <<ULong:64/native-unsigned-integer, _Rest/binary>> = Binary
  610
+        <<ULong:64/native-unsigned-integer, _Rest/binary>> = Binary
663 611
 
664  
-    **FFI_HARDCODED_SIZEOF_<TYPE>**
  612
+- **FFI_HARDCODED_SIZEOF_<TYPE>**
665 613
 
666  
-        The type size in *bytes*
  614
+    The type size in *bytes*
667 615
 
668  
-    **FFI_HARDCODED_<TYPE>_BITS**
  616
+- **FFI_HARDCODED_<TYPE>_BITS**
669 617
 
670  
-        The type size in *bits*
  618
+    The type size in *bits*
671 619
 
672  
-As implied by their name, the ``ffi_hardcodes.hrl`` contents are
  620
+As implied by their name, the `ffi_hardcodes.hrl` contents are
673 621
 *specific to the build platform*, and when they are used, they will be
674 622
 hard-coded in the resulting ``.beam`` files.  Thus, these macros
675 623
 should be avoided if a developer expects his/her FFI-based code to be
@@ -678,11 +626,10 @@ FFI type sizes in a portable way is the `ffi:sizeof/1`_ function.
678 626
 
679 627
 
680 628
 Further notes
681  
-=============
  629
+-------------
682 630
 
683 631
 
684  
-Notes on FFI preloading
685  
------------------------
  632
+### Notes on FFI preloading ###
686 633
 
687 634
 When a library is loaded with `erl_ddll:load_library/3`_, it may be
688 635
 reloaded or unloaded just like any Erlang linked-in driver.  If the
@@ -700,8 +647,7 @@ reloaded or unloaded just like any Erlang linked-in driver.  If the
700 647
   `ffi:raw_call/2`_).
701 648
 
702 649
 
703  
-Notes on vararg functions
704  
--------------------------
  650
+### Notes on vararg functions ###
705 651
 
706 652
 `ffi:call/3`_ and `ffi:raw_call/3`_ may be used to call vararg C
707 653
 functions, simply by providing the desired number of arguments.
@@ -710,7 +656,7 @@ In order to exploit the preloading optimizations, however, it is
710 656
 necessary to use a different preload for each different function call
711 657
 signature.  For example, if a developer is going to call ``printf()``
712 658
 with different arguments, he/she will need to use a preloading list
713  
-like the following one: ::
  659
+like the following one:
714 660
 
715 661
     ok = erl_ddll:load_library("/lib", libc,
716 662
                                [{preload,
@@ -720,8 +666,7 @@ like the following one: ::
720 666
                                   {printf, {sint, cstring, cstring}}]}]).
721 667
 
722 668
 
723  
-Notes on C pointers and Erlang binaries
724  
----------------------------------------
  669
+### Notes on C pointers and Erlang binaries ###
725 670
 
726 671
 As reported in the Appendix_, an Erlang binary can be passed to a C
727 672
 function as a 'pointer' value.  In this case, the C function will
@@ -733,8 +678,7 @@ the 'binary' FFI type (see next paragraph) or copy the data itself in
733 678
 a safe place.
734 679
 
735 680
 
736  
-Notes on Erlang binaries and reference counting
737  
------------------------------------------------
  681
+### Notes on Erlang binaries and reference counting ###
738 682
 
739 683
 As reported in the Appendix_, when the 'binary' FFI type is used as
740 684
 argument, the C function will also receive a binary (in the form of an
@@ -760,56 +704,55 @@ passed to, or returned from, the C side through a FFI call.
760 704
    call ``driver_binary_dec_refc()`` before returning.
761 705
 
762 706
 
763  
-Notes on type-tagged values
764  
----------------------------
  707
+### Notes on type-tagged values ###
765 708
 
766 709
 As reported above, the high-level FFI API is based on type-tagged
767 710
 values.  Type tags, however, may introduce yet another way to
768 711
 annotate/represent the types of Erlang function parameters --- and it
769 712
 may become an annoying redundancy, expecially now that type contracts
770  
-are (probably) going to be introduced in Erlang [12]_.
  713
+are (probably) going to be introduced in Erlang [12][].
771 714
 
772 715
 Thus, the high-level FFI API should be considered highly experimental
773 716
 and subject to change, depending on how type contracts will allow to
774  
-achieve the same tasks (see `High-level API`_).  This issue will need
  717
+achieve the same tasks (see [High-level API][]).  This issue will need
775 718
 to be explored if/when contracts will be available in the standard
776 719
 Erlang/OTP distribution.
777 720
 
778 721
 
779 722
 Backwards Compatibility
780  
-=======================
  723
+-----------------------
781 724
 
782 725
 This EEP, and the proposed FFI patches (see below), do not introduce
783 726
 incompatibilities with the standard OTP release.  However, three
784 727
 (possibly) relevant internal changes are required:
785 728
 
786  
-1. the ``driver_binary_dec_refc()`` function must be allowed to
  729
+1. the `driver_binary_dec_refc()` function must be allowed to
787 730
    reach the refcount of 0 without errors or warnings (even when
788 731
    debugging).  This is necessary in order to allow a C function to
789 732
    create a binary, drop its references and return it to the Erlang VM
790 733
    (see `Notes on Erlang binaries and reference counting`_);
791 734
 
792 735
 2. as a consequence of the previous point,
793  
-   ``driver_binary_inc_refc()`` must be allowed to reach a minimum
  736
+   `driver_binary_inc_refc()` must be allowed to reach a minimum
794 737
    refcount of 1 without errors or warnings (the current minimum value
795 738
    is 2);
796 739
 
797  
-3. the ``iolist()`` -> ``ErlIOVec`` conversion code in ``io.c`` needs
  740
+3. the `iolist()` -> `ErlIOVec` conversion code in `io.c` needs
798 741
    to be exposed as a stand-alone function, to be used by the FFI.
799 742
 
800 743
 
801 744
 Reference implementation
802  
-========================
  745
+------------------------
803 746
 
804  
-An implementation of this EEP is available on [4]_ as a set of patches
  747
+An implementation of this EEP is available on [4][] as a set of patches
805 748
 against OTP R11B-5.
806 749
 
807  
-The code is based on the GCC FFI library (libffi) [5]_.  libffi is
  750
+The code is based on the GCC FFI library (libffi) [5][].  libffi is
808 751
 multi-platform, can be packaged and used separately from the GCC
809 752
 source code, and is released under a very permissive license [6]_
810 753
 (compatible with the Erlang Public License).  It has been used to
811 754
 implement the FFI interface of several applications and languages,
812  
-including Python [7]_.
  755
+including [Python] [7].
813 756
 
814 757
 The current EEP implementation looks for libffi on the build system,
815 758
 and links the Erlang emulator against it (preferring the libffi shared
@@ -827,131 +770,128 @@ feedback.
827 770
 
828 771
 
829 772
 References
830  
-==========
  773
+----------
831 774
 
832  
-.. [1] IG: the Erlang Interface Generator, Törnquist and Lundell 
833  
-       http://www1.erlang.org/documentation/doc-4.8.2/lib/ig-1.8/doc/index.html
  775
+[1]: http://www1.erlang.org/documentation/doc-4.8.2/lib/ig-1.8/doc/index.html
  776
+     "IG: the Erlang Interface Generator, Törnquist and Lundell" 
834 777
 
835  
-.. [2] The Evolution of Erlang Drivers and the Erlang Driver Toolkit, Fritchie
836  
-       http://www.erlang.se/workshop/2002/Fritchie.pdf
  778
+[2]: http://www.erlang.se/workshop/2002/Fritchie.pdf
  779
+     "The Evolution of Erlang Drivers and the Erlang Driver Toolkit, Fritchie"
837 780
 
838  
-.. [3] The Dryverl Erlang/C binding compiler
839  
-       http://dryverl.objectweb.org/
  781
+[3]: http://dryverl.objectweb.org/
  782
+     "The Dryverl Erlang/C binding compiler"
840 783
 
841  
-.. [4] Foreign Function Interface (FFI) for Erlang/OTP
842  
-       http://muvara.org/crs4/erlang/ffi
  784
+[4]: http://muvara.org/crs4/erlang/ffi
  785
+     "Foreign Function Interface (FFI) for Erlang/OTP"
843 786
 
844  
-.. [5] libffi: the GCC Foreign Function Interface Library
845  
-       http://gcc.gnu.org/viewcvs/trunk/libffi/
  787
+[5]: http://gcc.gnu.org/viewcvs/trunk/libffi/
  788
+    "libffi: the GCC Foreign Function Interface Library"
846 789
 
847  
-.. [6] The libffi license
848  
-       `http://gcc.gnu.org/viewcvs/*checkout*/trunk/libffi/LICENSE <http://gcc.gnu.org/viewcvs/*checkout*/trunk/libffi/LICENSE>`_
  790
+[6]: http://gcc.gnu.org/viewcvs/checkout/trunk/libffi/LICENSE
  791
+    "The libffi license"
849 792
 
850  
-.. [7] The CPython package
851  
-       http://python.net/crew/theller/ctypes/
  793
+[7]: http://python.net/crew/theller/ctypes/
  794
+    "The CPython package"
852 795
 
853  
-.. [8] The Haskell 98 Foreign Function Interface
854  
-       http://www.cse.unsw.edu.au/~chak/haskell/ffi/
  796
+[8]: http://www.cse.unsw.edu.au/~chak/haskell/ffi/
  797
+     "The Haskell 98 Foreign Function Interface"
855 798
 
856  
-.. [9] The Java Native Interface
857  
-       http://java.sun.com/j2se/1.5.0/docs/guide/jni/
  799
+[9]: http://java.sun.com/j2se/1.5.0/docs/guide/jni/
  800
+    "The Java Native Interface"
858 801
 
859  
-.. [10] Extending and Embedding the Python Interpreter
860  
-        http://docs.python.org/ext/ext.html
  802
+[10]: http://docs.python.org/ext/ext.html
  803
+     "Extending and Embedding the Python Interpreter"
861 804
 
862  
-.. [11] Python/C API Reference Manual
863  
-        http://docs.python.org/api/api.html
  805
+[11]: http://docs.python.org/api/api.html
  806
+     "Python/C API Reference Manual"
864 807
 
865  
-.. [12] A Language for Specifying Type Contracts in Erlang and its
  808
+[12]: http://user.it.uu.se/~kostis/Papers/contracts.pdf
  809
+     "A Language for Specifying Type Contracts in Erlang and its
866 810
         Interaction with Success Typings, Jiménez Lindahl and Sagonas
867  
-        (Presented at the 2007 SIGPLAN Erlang Workshop).
868  
-        Paper: http://user.it.uu.se/~kostis/Papers/contracts.pdf
869  
-        Slides: http://www.erlang.se/workshop/2007/proceedings/03lindah.pdf
  811
+        (Presented at the 2007 SIGPLAN Erlang Workshop)."
870 812
 
871 813
 Appendix
872  
-========
  814
+--------
873 815
 
874  
-Erlang-to-C automatic type conversions
875  
---------------------------------------
  816
+### Erlang-to-C automatic type conversions ###
876 817
 
877 818
 The following table reports the Erlang-to-C conversions, used for
878 819
 passing Erlang terms as C function call arguments.
879 820
 
880  
-====================== ===============================
881  
- C argument type        Supported Erlang types
882  
-====================== ===============================
883  
-uchar                  integer()
884  
-schar                  integer()
885  
-ushort                 integer()
886  
-sshort                 integer()
887  
-uint                   integer()
888  
-sint                   integer()
889  
-ulong                  integer()
890  
-slong                  integer()
891  
-uint8                  integer()
892  
-sint8                  integer()
893  
-uint16                 integer()
894  
-sint16                 integer()
895  
-uint32                 integer()
896  
-sint32                 integer()
897  
-uint64                 integer()
898  
-sint64                 integer()
899  
-float                  float()
900  
-double                 float()
901  
-longdouble             float()
902  
-pointer                binary() | integer()
903  
-cstring                binary() | integer()
904  
-nonnull                binary() | integer()
905  
-size_t                 integer()
906  
-ssize_t                integer()
907  
-pid_t                  integer()
908  
-off_t                  integer()
909  
-binary                 binary()
910  
-erliovec               iolist()
911  
-====================== ===============================
912  
-
913  
-
914  
-C-to-Erlang automatic type conversions
915  
---------------------------------------
  821
+    ====================== ===============================
  822
+     C argument type        Supported Erlang types
  823
+    ====================== ===============================
  824
+    uchar                  integer()
  825
+    schar                  integer()
  826
+    ushort                 integer()
  827
+    sshort                 integer()
  828
+    uint                   integer()
  829
+    sint                   integer()
  830
+    ulong                  integer()
  831
+    slong                  integer()
  832
+    uint8                  integer()
  833
+    sint8                  integer()
  834
+    uint16                 integer()
  835
+    sint16                 integer()
  836
+    uint32                 integer()
  837
+    sint32                 integer()
  838
+    uint64                 integer()
  839
+    sint64                 integer()
  840
+    float                  float()
  841
+    double                 float()
  842
+    longdouble             float()
  843
+    pointer                binary() | integer()
  844
+    cstring                binary() | integer()
  845
+    nonnull                binary() | integer()
  846
+    size_t                 integer()
  847
+    ssize_t                integer()
  848
+    pid_t                  integer()
  849
+    off_t                  integer()
  850
+    binary                 binary()
  851
+    erliovec               iolist()
  852
+    ====================== ===============================
  853
+
  854
+
  855
+### C-to-Erlang automatic type conversions ###
916 856
 
917 857
 The following table reports the C-to-Erlang conversions, used for
918 858
 converting C function return values into Erlang terms.
919 859
 
920  
-====================== ===============================
921  
- C return type          Resulting Erlang type
922  
-====================== ===============================
923  
-uchar                  integer()
924  
-schar                  integer()
925  
-ushort                 integer()
926  
-sshort                 integer()
927  
-uint                   integer()
928  
-sint                   integer()
929  
-ulong                  integer()
930  
-slong                  integer()
931  
-uint8                  integer()
932  
-sint8                  integer()
933  
-uint16                 integer()
934  
-sint16                 integer()
935  
-uint32                 integer()
936  
-sint32                 integer()
937  
-uint64                 integer()
938  
-sint64                 integer()
939  
-float                  float()
940  
-double                 float()
941  
-longdouble             float()
942  
-pointer                integer()
943  
-cstring                integer()
944  
-nonnull                integer()
945  
-size_t                 integer()
946  
-ssize_t                integer()
947  
-off_t                  integer()
948  
-pid_t                  integer()
949  
-binary                 binary()
950  
-====================== ===============================
  860
+    ====================== ===============================
  861
+     C return type          Resulting Erlang type
  862
+    ====================== ===============================
  863
+    uchar                  integer()
  864
+    schar                  integer()
  865
+    ushort                 integer()
  866
+    sshort                 integer()
  867
+    uint                   integer()
  868
+    sint                   integer()
  869
+    ulong                  integer()
  870
+    slong                  integer()
  871
+    uint8                  integer()
  872
+    sint8                  integer()
  873
+    uint16                 integer()
  874
+    sint16                 integer()
  875
+    uint32                 integer()
  876
+    sint32                 integer()
  877
+    uint64                 integer()
  878
+    sint64                 integer()
  879
+    float                  float()
  880
+    double                 float()
  881
+    longdouble             float()
  882
+    pointer                integer()
  883
+    cstring                integer()
  884
+    nonnull                integer()
  885
+    size_t                 integer()
  886
+    ssize_t                integer()
  887
+    off_t                  integer()
  888
+    pid_t                  integer()
  889
+    binary                 binary()
  890
+    ====================== ===============================
951 891
 
952 892
 
953 893
 Copyright
954  
-=========
  894
+---------
955 895
 
956 896
 Copyright (C) 2007 by CRS4 (Center for Advanced Studies, Research and
957 897
 Development in Sardinia) - http://www.crs4.it/
78  eeps/eep-0008.md
Source Rendered
... ...
@@ -1,14 +1,14 @@
1  
-EEP: 8
2  
-Title: Types and function specifications
3  
-Version: $Revision$
4  
-Last-Modified: $Date$
5  
-Author: Tobias Lindahl [tobias(dot)lindahl(at)it(dot)uu(dot)se], Kostis Sagonas [kostis(at)it(dot)uu(dot)se]
6  
-Status: Draft
7  
-Type: Standards Track
8  
-Content-Type: text/x-rst
9  
-Created: 2-Dec-2007
10  
-Erlang-Version: R12B
11  
-Post-History: 
  1
+EEP 8: Types and function specifications
  2
+====
  3
+
  4
+    Author: Tobias Lindahl [tobias(dot)lindahl(at)it(dot)uu(dot)se], Kostis Sagonas [kostis(at)it(dot)uu(dot)se]
  5
+    Status: Draft
  6
+    Type: Standards Track
  7
+    Content-Type: text/x-markdown
  8
+    Created: 2-Dec-2007
  9
+    Erlang-Version: R12B
  10
+
  11
+====
12 12
 
13 13
 Abstract
14 14
 ========
@@ -36,6 +36,7 @@ Specification
36 36
 
37 37
 Types and their syntax
38 38
 ----------------------
  39
+
39 40
 Types describe sets of Erlang terms. Types consist and are built from
40 41
 a set of predefined types (e.g. ``integer()``, ``atom()``, ``pid()``, ...)
41 42
 described below. Predefined types represent a typically infinite set
@@ -157,25 +158,21 @@ violation results in a compilation error. (For bootstrapping purposes,
157 158
 it can also result to just a warning if this involves a built-in type
158 159
 which has just been introduced.)
159 160
 
160  
-    *NOTE*: The following built-in list types also exist, but they are
161  
-    expected to be rarely used. Hence, they have long names:
  161
+**NOTE**: The following built-in list types also exist, but they are
  162
+expected to be rarely used. Hence, they have long names:
162 163
 
163  
-    ::
  164
+    nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any())
  165
+    nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())
164 166
 
165  
-        nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any())
166  
-        nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())
  167
+where the following two types
167 168
 
168  
-    where the following two types
  169
+    nonempty_improper_list(Type1, Type2)
  170
+    nonempty_maybe_improper_list(Type1, Type2)
169 171
 
170  
-    ::
171  
-
172  
-        nonempty_improper_list(Type1, Type2)
173  
-	nonempty_maybe_improper_list(Type1, Type2)
174  
-
175  
-    define the set of Erlang terms one would expect.
  172
+define the set of Erlang terms one would expect.
176 173
 
177 174
 Also for convenience, we allow for record notation to be used. Records
178  
-are just shorthands for the corresponding tuples. ::
  175
+are just shorthands for the corresponding tuples:
179 176
 
180 177
     Record :: #Erlang_Atom{}
181 178
             | #Erlang_Atom{Fields}
@@ -186,9 +183,10 @@ is described in Section 3 below.
186 183
 
187 184
 Type declarations of user-defined types
188 185
 ---------------------------------------
  186
+
189 187
 As seen, the basic syntax of a type is an atom followed by closed
190 188
 parentheses. New types are declared using ``'type'`` compiler attributes
191  
-as in the following::
  189
+as in the following:
192 190
 
193 191
     -type my_type() :: Type.
194 192
 
@@ -206,7 +204,7 @@ Type declarations can also be parametrized by including type variables
206 204
 between the parentheses. The syntax of type variables is the same as
207 205
 Erlang variables (starts with an upper case letter). Naturally, these
208 206
 variables can - and should - appear on the RHS of the definition.
209  
-A concrete example appears below::
  207
+A concrete example appears below:
210 208
 
211 209
     -type orddict(Key, Val) :: [{Key, Val}].
212 210
 
@@ -214,17 +212,17 @@ A concrete example appears below::
214 212
 Type information in record declarations
215 213
 ---------------------------------------
216 214
 The types of record fields can be specified in the declaration of the
217  
-record. The syntax for this is::
  215
+record. The syntax for this is:
218 216
 
219 217
     -record(rec, {field1 :: Type1, field2, field3 :: Type3}).
220 218
 
221 219
 For fields without type annotations, their type defaults to ``any()``.
222  
-I.e., the above is a shorthand for::
  220
+I.e., the above is a shorthand for:
223 221
 
224 222
     -record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).
225 223
 
226 224
 In the presence of initial values for fields, the type must be
227  
-declared after the initialisation as in the following::
  225
+declared after the initialisation as in the following:
228 226
 
229 227
     -record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).
230 228
 
@@ -233,7 +231,7 @@ Naturally, the initial values for fields should be compatible with
233 231
 compiler and results in a compilation error if a violation is
234 232
 detected. For fields without initial values, the singleton type
235 233
 ``'undefined'`` is added to all declared types. In other words, the
236  
-following two record declarations have identical effects::
  234
+following two record declarations have identical effects:
237 235
 
238 236
     -record(rec, {f1 = 42 :: integer(),
239 237
                   f2      :: float(),
@@ -247,13 +245,13 @@ For this reason, it is recommended that records contain initializers,
247 245
 whenever possible.
248 246
 
249 247
 Any record, containing type information or not, once defined, can be
250  
-used as a type using the syntax::
  248
+used as a type using the syntax:
251 249
 
252 250
     #rec{}
253 251