From: Nicholas Ormrod Date: Fri, 17 Apr 2015 01:56:01 +0000 (-0700) Subject: README: Fixed typo, formatted code, and linked to docs X-Git-Tag: v0.36.0~27 X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=513a1e16ffa3f235765cd8ecb2fe949bf0692e52;p=folly.git README: Fixed typo, formatted code, and linked to docs Summary: (from @njormrod) This changes the READMEs to be .md, appropriate for github. I viewed the docs on github, and they looked WAY better as .md files. Signed-off-by: Nicholas Ormrod Test Plan: view on github Reviewed By: markisaa@fb.com Subscribers: fugalh, folly-diffs@, jsedgwick, yfeldblum, chalfant FB internal diff: D1999531 Tasks: 6783581 Signature: t1:1999531:1429220432:68c6d8dc70806d993c83cacce6369cb7e6e964c8 --- diff --git a/folly/experimental/exception_tracer/README b/folly/experimental/exception_tracer/README deleted file mode 100644 index 819f8547..00000000 --- a/folly/experimental/exception_tracer/README +++ /dev/null @@ -1,22 +0,0 @@ -Exception tracer library - -This library allows you to inspect the exception stack at runtime. -The library can be used in three ways: - -1. Link in the exception_tracer_base library. You get access to the functions -in ExceptionTracer.h, but no stack traces. This has no runtime overhead, -and is compliant with the C++ ABI. - -2. Link in the (full) exception_tracer library. You get access to the -functions in ExceptionTracer.h, the std::terminate and std::unexpected -handlers are installed by default, and you get full stack traces with -all exceptions. This has some runtime overhead (the stack trace must be -captured and stored whenever an exception is thrown) added to throw -and catch, but no runtime overhead otherwise. This is less portable -(depends on internal details of GNU's libstdc++). - -3. LD_PRELOAD libexceptiontracer.so. This is equivalent to #2 above, but -requires no link-time changes. On the other hand, you need to ensure that -libexceptiontracer.so is compiled with the same compiler and flags as -your binary, and the usual caveats about LD_PRELOAD apply (it propagates -to child processes, etc). diff --git a/folly/experimental/exception_tracer/README.md b/folly/experimental/exception_tracer/README.md new file mode 100644 index 00000000..819f8547 --- /dev/null +++ b/folly/experimental/exception_tracer/README.md @@ -0,0 +1,22 @@ +Exception tracer library + +This library allows you to inspect the exception stack at runtime. +The library can be used in three ways: + +1. Link in the exception_tracer_base library. You get access to the functions +in ExceptionTracer.h, but no stack traces. This has no runtime overhead, +and is compliant with the C++ ABI. + +2. Link in the (full) exception_tracer library. You get access to the +functions in ExceptionTracer.h, the std::terminate and std::unexpected +handlers are installed by default, and you get full stack traces with +all exceptions. This has some runtime overhead (the stack trace must be +captured and stored whenever an exception is thrown) added to throw +and catch, but no runtime overhead otherwise. This is less portable +(depends on internal details of GNU's libstdc++). + +3. LD_PRELOAD libexceptiontracer.so. This is equivalent to #2 above, but +requires no link-time changes. On the other hand, you need to ensure that +libexceptiontracer.so is compiled with the same compiler and flags as +your binary, and the usual caveats about LD_PRELOAD apply (it propagates +to child processes, etc). diff --git a/folly/wangle/rx/README b/folly/wangle/rx/README deleted file mode 100644 index ee170f35..00000000 --- a/folly/wangle/rx/README +++ /dev/null @@ -1,36 +0,0 @@ -Rx is a pattern for "functional reactive programming" that started at -Microsoft in C#, and has been reimplemented in various languages, notably -RxJava for JVM languages. - -It is basically the plural of Futures (a la Wangle). - - - singular | plural - +---------------------------------+----------------------------------- - sync | Foo getData() | std::vector getData() - async | wangle::Future getData() | wangle::Observable getData() - - -For more on Rx, I recommend these resources: - -Netflix blog post (RxJava): http://techblog.netflix.com/2013/02/rxjava-netflix-api.html -Introduction to Rx eBook (C#): http://www.introtorx.com/content/v1.0.10621.0/01_WhyRx.html -The RxJava wiki: https://github.com/Netflix/RxJava/wiki -Netflix QCon presentation: http://www.infoq.com/presentations/netflix-functional-rx -https://rx.codeplex.com/ - -There are open source C++ implementations, I haven't looked at them. They -might be the best way to go rather than writing it NIH-style. I mostly did it -as an exercise, to think through how closely we might want to integrate -something like this with Wangle, and to get a feel for how it works in C++. - -I haven't even tried to support move-only data in this version. I'm on the -fence about the usage of shared_ptr. Subject is underdeveloped. A whole rich -set of operations is obviously missing. I haven't decided how to handle -subscriptions (and therefore cancellation), but I'm pretty sure C#'s -"Disposable" is thoroughly un-C++ (opposite of RAII). So for now subscribe -returns nothing at all and you can't cancel anything ever. The whole thing is -probably riddled with lifetime corner case bugs that will come out like a -swarm of angry bees as soon as someone tries an infinite sequence, or tries to -partially observe a long sequence. I'm pretty sure subscribeOn has a bug that -I haven't tracked down yet. diff --git a/folly/wangle/rx/README.md b/folly/wangle/rx/README.md new file mode 100644 index 00000000..0f7f6972 --- /dev/null +++ b/folly/wangle/rx/README.md @@ -0,0 +1,36 @@ +Rx is a pattern for "functional reactive programming" that started at +Microsoft in C#, and has been reimplemented in various languages, notably +RxJava for JVM languages. + +It is basically the plural of Futures (a la Wangle). + +``` + singular | plural + +---------------------------------+----------------------------------- + sync | Foo getData() | std::vector getData() + async | wangle::Future getData() | wangle::Observable getData() +``` + +For more on Rx, I recommend these resources: + +Netflix blog post (RxJava): http://techblog.netflix.com/2013/02/rxjava-netflix-api.html +Introduction to Rx eBook (C#): http://www.introtorx.com/content/v1.0.10621.0/01_WhyRx.html +The RxJava wiki: https://github.com/Netflix/RxJava/wiki +Netflix QCon presentation: http://www.infoq.com/presentations/netflix-functional-rx +https://rx.codeplex.com/ + +There are open source C++ implementations, I haven't looked at them. They +might be the best way to go rather than writing it NIH-style. I mostly did it +as an exercise, to think through how closely we might want to integrate +something like this with Wangle, and to get a feel for how it works in C++. + +I haven't even tried to support move-only data in this version. I'm on the +fence about the usage of shared_ptr. Subject is underdeveloped. A whole rich +set of operations is obviously missing. I haven't decided how to handle +subscriptions (and therefore cancellation), but I'm pretty sure C#'s +"Disposable" is thoroughly un-C++ (opposite of RAII). So for now subscribe +returns nothing at all and you can't cancel anything ever. The whole thing is +probably riddled with lifetime corner case bugs that will come out like a +swarm of angry bees as soon as someone tries an infinite sequence, or tries to +partially observe a long sequence. I'm pretty sure subscribeOn has a bug that +I haven't tracked down yet.