Mercurial > hg > orthanc
diff Plugins/Include/orthanc/OrthancCPlugin.h @ 1595:e1e54a73ba8b
OrthancPluginRegisterRestCallbackNoLock, documentation
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Thu, 27 Aug 2015 14:58:58 +0200 |
parents | 2bac60a4f584 |
children | f2e3d030ea59 |
line wrap: on
line diff
--- a/Plugins/Include/orthanc/OrthancCPlugin.h Thu Aug 27 12:56:48 2015 +0200 +++ b/Plugins/Include/orthanc/OrthancCPlugin.h Thu Aug 27 14:58:58 2015 +0200 @@ -17,7 +17,7 @@ * - Possibly register its callback for received DICOM instances using ::OrthancPluginRegisterOnStoredInstanceCallback(). * - Possibly register its callback for changes to the DICOM store using ::OrthancPluginRegisterOnChangeCallback(). * - Possibly register a custom storage area using ::OrthancPluginRegisterStorageArea(). - * - Possibly register a custom database back-end area using ::OrthancPluginRegisterDatabaseBackend(). + * - Possibly register a custom database back-end area using OrthancPluginRegisterDatabaseBackend(). * -# <tt>void OrthancPluginFinalize()</tt>: * This function is invoked by Orthanc during its shutdown. The plugin * must free all its memory. @@ -29,8 +29,11 @@ * The name and the version of a plugin is only used to prevent it * from being loaded twice. * - * The various REST callbacks are guaranteed to be executed in mutual - * exclusion since Orthanc 0.8.5. + * To ensure multi-threading safety, the various REST callbacks are + * guaranteed to be executed in mutual exclusion since Orthanc + * 0.8.5. If this feature is undesired (notably when developing + * high-performance plugins handling simultaneous requests), use + * ::OrthancPluginRegisterRestCallbackNoLock(). **/ @@ -361,6 +364,7 @@ _OrthancPluginService_RegisterOnStoredInstanceCallback = 1001, _OrthancPluginService_RegisterStorageArea = 1002, _OrthancPluginService_RegisterOnChangeCallback = 1003, + _OrthancPluginService_RegisterRestCallbackNoLock = 1004, /* Sending answers to REST calls */ _OrthancPluginService_AnswerBuffer = 2000, @@ -857,10 +861,13 @@ * expression for a URI. This function must be called during the * initialization of the plugin, i.e. inside the * OrthancPluginInitialize() public function. + * + * Each REST callback is guaranteed to run in mutual exclusion. * * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). * @param pathRegularExpression Regular expression for the URI. May contain groups. * @param callback The callback function to handle the REST call. + * @see OrthancPluginRegisterRestCallbackNoLock() **/ ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallback( OrthancPluginContext* context, @@ -875,6 +882,39 @@ + /** + * @brief Register a REST callback, without locking. + * + * This function registers a REST callback against a regular + * expression for a URI. This function must be called during the + * initialization of the plugin, i.e. inside the + * OrthancPluginInitialize() public function. + * + * Contrarily to OrthancPluginRegisterRestCallback(), the callback + * will NOT be invoked in mutual exclusion. This can be useful for + * high-performance plugins that must handle concurrent requests + * (Orthanc uses a pool of threads, one thread being assigned to + * each incoming HTTP request). Of course, it is up to the plugin to + * implement the required locking mechanisms. + * + * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). + * @param pathRegularExpression Regular expression for the URI. May contain groups. + * @param callback The callback function to handle the REST call. + * @see OrthancPluginRegisterRestCallback() + **/ + ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallbackNoLock( + OrthancPluginContext* context, + const char* pathRegularExpression, + OrthancPluginRestCallback callback) + { + _OrthancPluginRestCallback params; + params.pathRegularExpression = pathRegularExpression; + params.callback = callback; + context->InvokeService(context, _OrthancPluginService_RegisterRestCallbackNoLock, ¶ms); + } + + + typedef struct { OrthancPluginOnStoredInstanceCallback callback; @@ -2468,7 +2508,7 @@ * This function returns the description of a given error code. * * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). - * @param code The error code of interest. + * @param error The error code of interest. * @return The error description. This is a statically-allocated * string, do not free it. **/ @@ -2520,6 +2560,8 @@ * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). * @param output The HTTP connection to the client application. * @param status The HTTP status code to be sent. + * @param body The body of the answer. + * @param bodySize The size of the body. * @see OrthancPluginSendHttpStatusCode() **/ ORTHANC_PLUGIN_INLINE void OrthancPluginSendHttpStatus(