You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by rn...@apache.org on 2015/10/01 17:03:56 UTC
[7/7] couchdb-couch-epi git commit: Update documentation
Update documentation
Project: http://git-wip-us.apache.org/repos/asf/couchdb-couch-epi/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-couch-epi/commit/6cb1b9ca
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-couch-epi/tree/6cb1b9ca
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-couch-epi/diff/6cb1b9ca
Branch: refs/heads/master
Commit: 6cb1b9ca98a3e5bcf6fc72e791e13a07a564cf0c
Parents: d6c5081
Author: ILYA Khlopotov <ii...@ca.ibm.com>
Authored: Mon Sep 28 09:20:15 2015 -0700
Committer: ILYA Khlopotov <ii...@ca.ibm.com>
Committed: Thu Oct 1 07:29:39 2015 -0700
----------------------------------------------------------------------
README.md | 92 +++++++++++++++++++++++-----------------------
src/couch_epi.erl | 1 -
src/couch_epi_sup.erl | 4 +-
3 files changed, 48 insertions(+), 49 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb-couch-epi/blob/6cb1b9ca/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index e6bddb6..3f15a62 100644
--- a/README.md
+++ b/README.md
@@ -20,32 +20,27 @@
## Support release upgrade
-We monitor the source of config information and have an ability to notify the subscriber.
-The source is either a file for a `couch_epi_data_source` or module for `couch_epi_functions`.
+We monitor the modules involved in configuration of the service/provider so we
+get notified when there is a code upgrade. We use this notification in order to:
-If the subscriber wants to receive notifications when the config has been updated it can use:
+ - regenerate dispatch module if needed
+ - call notify/3 of a module implementing couch_epi_plugin behaviour
- couch_epi:subscribe(App, Key, Module, Func, ExtraArgs)
-
-The function would be called with following arguments
-
- Fun(App :: app(), Key :: key(),
- OldData :: notification(), NewData :: notification(),
- ExtraArgs :: term()
-
-The `notification()` is either `{data, term()}` or `{modules, [module()]}`
+Call to notify/3 would be called for both providers and data_providers.
## data example
Any application that wants to register some configuration data for a service using module
-could add an entry in its supervision tree with something like:
+could add an entry in its implementation of couch_epi_plugin behaviour:
- Spec = couch_epi_data:childspec(
- appname_stats, %% Id
- appname, %% CurrentApp
- {epi_key, {couch_stats, definitions}},
- appname_stats_config %% Module
- ).
+ data_providers() ->
+ [
+ {{couch_stats, descriptions},
+ {priv_file, "stats_descriptions.cfg"}, [{interval, 5000}]}
+ {{couch_stats, descriptions},
+ {file, "/tmp/extra_stats.cfg"}, [{interval, 5000}]},
+ {{couch_stats, descriptions}, {module, my_stats}}
+ ].
When service provider wants to learn about all the installed config data for it to use
it would then just do something like:
@@ -53,6 +48,12 @@ it would then just do something like:
couch_epi:get(Handle, Service, Key)
+The service provider also have to mention the data keys it is using in its
+implementation of couch_epi_plugin behaviour
+
+ data_subscriptions() ->
+ [{couch_stats, descriptions}].
+
There are also additional functions to get the same data in various formats
- `couch_epi:all(Handle)` - returns config data for all services for a given handle
@@ -65,38 +66,22 @@ There are also additional functions to get the same data in various formats
- `couch_epi:subscribers(Handle)` - return list of known subscribers
-
-## data_source example
-
-Any application that wants to register some configuration data for a service
-could add an entry in its supervision tree with something like:
-
- Spec = couch_epi_data_source:childspec(
- appname_stats, %% Id
- appname, %% CurrentApp
- {epi_key, {couch_stats, definitions}},
- {priv_file, "couch_stats.cfg"},
- [{interval, 5000}]
- ).
-
-Note we also support `{file, FilePath}` instead of `{priv_file, File}`
-
-The query API is the same as for `data` (see `data example`)
-
# Function dispatch example
-Any application that wants to register some functions for a service
-could add an entry in its supervision tree with something like:
+Any application that wants to register implementation functions for a service
+could add following into it's implementation of couch_epi_plugin behaviour:
+
+ providers() ->
+ [{my_service, module_which_implements_the_functions}].
- Spec = couch_epi_functions:childspec(
- appname_stats, %% child id
- appname, %% CurrentApp
- my_service,
- my_module %% Module
- ).
+Adding the entry would generate a dispatch methods for any exported function
+of modules passed.
-Adding the entry would generate a dispatch methods for any exported function of modules passed.
+Services have to be defined in one of the implementations of couch_epi_plugin
+behaviour as:
+ services() ->
+ [{my_service, module_to_monitor_for_codechange}].
When app wants to dispatch the call to all service providers it calls
@@ -111,3 +96,18 @@ There are multiple ways of doing the apply which is controlled by Opts
Notes:
- `concurrent` is incompatible with `pipe`
+
+# couch_epi_plugin behaviour
+
+The module implementing behaviour need to export following functions:
+
+ - Module:app/0 - Returns atom representing the application name
+ - Module:providers/0 - Returns list of {service_id(), module()} tuples
+ for defined providers
+ - Module:services/0 - Returns list of {service_id(), module()} tuples
+ for defined services
+ - Module:data_subscriptions/0 - Returns list of keys we define
+ - Module:data_providers/0 - Returns list of keys we provide
+ - Module:processes/0 - Supervisor specs which we would be injected into
+ application supervisor
+ - Module:notify/3 - Notification callback
http://git-wip-us.apache.org/repos/asf/couchdb-couch-epi/blob/6cb1b9ca/src/couch_epi.erl
----------------------------------------------------------------------
diff --git a/src/couch_epi.erl b/src/couch_epi.erl
index ab3703e..2cb4a1a 100644
--- a/src/couch_epi.erl
+++ b/src/couch_epi.erl
@@ -12,7 +12,6 @@
-module(couch_epi).
-%% subscribtion management
-export([get_handle/1]).
-export([register_service/1]).
http://git-wip-us.apache.org/repos/asf/couchdb-couch-epi/blob/6cb1b9ca/src/couch_epi_sup.erl
----------------------------------------------------------------------
diff --git a/src/couch_epi_sup.erl b/src/couch_epi_sup.erl
index 77d81b4..030095b 100644
--- a/src/couch_epi_sup.erl
+++ b/src/couch_epi_sup.erl
@@ -12,10 +12,10 @@
-module(couch_epi_sup).
-%% ----------------------------------
+%% --------------------
%% Important assumption
%% ====================
-%% Keeper and codechange_monitor childspecs relie on underdocumented feature.
+%% Keeper and codechange_monitor childspecs rely on undocumented behaviour.
%% According to supervisor docs:
%% ...if the child process is a supervisor, gen_server, or gen_fsm, this
%% should be a list with one element [Module].