Peter M. Groen / FlashMQ

Commit 541ef599da480739587cebd6b33ec19545a5cbf3

Authored by Wiebe Cazemier
1 parent 57b89866

Update auth plugin doc 

Especially remove the flashmq_auth_plugin_allocate_global_memory(),
which was an old idea.
Inline Side-by-side
Showing 1 changed file with 12 additions and 14 deletions
flashmq_plugin.h
  View file @541ef59
... ... @@ -4,8 +4,8 @@
4 4 *
5 5 * This interface definition is public domain and you are encouraged
6 6 * to copy it to your authentication plugin project, for portability. Including
7   - * this file in your project does not require your code to have a compatibile
8   - * license nor requires you to open source it.
  7 + * this file in your project does not make it a 'derived work', does not require
  8 + * your code to have a compatibile license nor requires you to open source it.
9 9 *
10 10 * Compile like: gcc -fPIC -shared authplugin.cpp -o authplugin.so
11 11 */
... ... @@ -79,7 +79,8 @@ struct FlashMQMessage
79 79 };
80 80  
81 81 /**
82   - * @brief flashmq_logf calls the internal logger of FlashMQ. The logger mutexes all access, so is thread-safe.
  82 + * @brief flashmq_logf calls the internal logger of FlashMQ. The logger mutexes all access, so is thread-safe, and writes to disk
  83 + * asynchronously, so it won't hold you up.
83 84 * @param level is any of the levels defined above, starting with LOG_.
84 85 * @param str
85 86 *
... ... @@ -96,17 +97,14 @@ int flashmq_auth_plugin_version();
96 97 /**
97 98 * @brief flashmq_auth_plugin_allocate_thread_memory is called once by each thread. Never again.
98 99 * @param thread_data. Create a memory structure and assign it to *thread_data.
99   - * @param global_data. The global data created in flashmq_auth_plugin_allocate_global_memory, if you use it.
100 100 * @param auth_opts. Map of flashmq_auth_opt_* from the config file.
101 101 *
102   - * Only allocate the plugin's memory here. Don't open connections, etc.
  102 + * Only allocate the plugin's memory here. Don't open connections, etc. That's because the reload mechanism doesn't call this function.
103 103 *
104   - * The global data is created by flashmq_auth_plugin_allocate_global_memory() and if you need it, you can assign it to your
105   - * own thread_data storage. It is not passed as argument to other functions.
  104 + * Because of the multi-core design of FlashMQ, you should treat each thread as its own domain with its own data. You can use static
  105 + * variables for global scope if you must, or even create threads, but do provide proper locking where necessary.
106 106 *
107   - * You can use static variables for global scope if you must, but do provide proper locking where necessary.
108   - *
109   - * throw an exception on errors.
  107 + * You can throw exceptions on errors.
110 108 */
111 109 void flashmq_auth_plugin_allocate_thread_memory(void **thread_data, std::unordered_map<std::string, std::string> &auth_opts);
112 110  
... ... @@ -115,7 +113,7 @@ void flashmq_auth_plugin_allocate_thread_memory(void **thread_data, std::unorder
115 113 * @param thread_data. Delete this memory.
116 114 * @param auth_opts. Map of flashmq_auth_opt_* from the config file.
117 115 *
118   - * throw an exception on errors.
  116 + * You can throw exceptions on errors.
119 117 */
120 118 void flashmq_auth_plugin_deallocate_thread_memory(void *thread_data, std::unordered_map<std::string, std::string> &auth_opts);
121 119  
... ... @@ -134,7 +132,7 @@ void flashmq_auth_plugin_deallocate_thread_memory(void *thread_data, std::unorde
134 132 * There is the option to set 'auth_plugin_serialize_init true' in the config file, which allows some mitigation in
135 133 * case you run into problems.
136 134 *
137   - * throw an exception on errors.
  135 + * You can throw exceptions on errors.
138 136 */
139 137 void flashmq_auth_plugin_init(void *thread_data, std::unordered_map<std::string, std::string> &auth_opts, bool reloading);
140 138  
... ... @@ -144,7 +142,7 @@ void flashmq_auth_plugin_init(void *thread_data, std::unordered_map&lt;std::string,
144 142 * @param auth_opts. Map of flashmq_auth_opt_* from the config file.
145 143 * @param reloading
146 144 *
147   - * throw an exception on errors.
  145 + * You can throw exceptions on errors.
148 146 */
149 147 void flashmq_auth_plugin_deinit(void *thread_data, std::unordered_map<std::string, std::string> &auth_opts, bool reloading);
150 148  
... ... @@ -162,7 +160,7 @@ void flashmq_auth_plugin_deinit(void *thread_data, std::unordered_map&lt;std::strin
162 160 *
163 161 * Implementing this is optional.
164 162 *
165   - * throw an exception on errors.
  163 + * You can throw exceptions on errors.
166 164 */
167 165 void flashmq_auth_plugin_periodic_event(void *thread_data);
168 166  
... ...