From 96beac0d50fe2442b4272968f604c8b69efd1b17 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Franti=C5=A1ek=20Dvo=C5=99=C3=A1k?= Date: Wed, 1 Dec 2004 16:45:46 +0000 Subject: [PATCH] Add documentation about fake substitute library. --- org.glite.lb.client/doc/README-fake | 132 ++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 org.glite.lb.client/doc/README-fake diff --git a/org.glite.lb.client/doc/README-fake b/org.glite.lb.client/doc/README-fake new file mode 100644 index 0000000..e2593ae --- /dev/null +++ b/org.glite.lb.client/doc/README-fake @@ -0,0 +1,132 @@ +Fake library +------------ + +Fake library is a substitute library designed for usage in unit tests of +programs which use L&B. The library implements a subset of L&B client API. +Implemented functions are dummy in the sense that they do not produce any +sideefect and they do not require any running services. + +Main purpose of the library is WMS unit testing, so it should contain all L&B +function calls used in WMS. + +List of implemented functions: + + 1) consumer API + + edg_wll_QueryEvents + edg_wll_QueryListener + edg_wll_JobLog + edg_wll_QuerySequenceCode + + 2) producer API + + edg_wll_Log* (functions for logging all event types) + edg_wll_LogEvent + edg_wll_LogEventSync + edg_wll_LogEventProxy + edg_wll_LogFlush + edg_wll_LogFlushAll + edg_wll_SetLoggingJob + edg_wll_SetLoggingJobProxy + edg_wll_RegisterJobSync + edg_wll_RegisterJob + edg_wll_RegisterSubjob + edg_wll_RegisterSubjobs + edg_wll_ChangeACL + + +Function calls always try to return some meaningful data. However, for testing +purposes a fine control on the returned value is usually required (e.g. to +cover both success and failure of the called function). Therefore the library +enables to set function error codes and/or adjust returned data. This is done +via callbacks. Callbacks are activated right before function end when all +pre-set data are available. + +Callbacks must be registered before using the library call. It is possible to +have only one registered callback for each registration type at once (see +below). Callback registration is global, it IS NOT thread safe. Otherwise +the library is thread safe in the same way as standard L&B library -- +functions may be called by multiple threads simultaneously provided that +more threads do not operate on a single L&B context at the same time. + +The following code fragments represent an example of unit test of a function +calling e.g. edg_wll_LogMatch() + +#include "glite/lb/producer_fake.h" + +int fail_EAGAIN_callback(edg_wll_Context ctx) +{ + return edg_wll_SetError(ctx,EAGAIN,"failure reason"); +} + +unit_test() +{ + /* sucessfull logging, edg_wll_LogMatch() called from + * tested_function() returns OK */ + + tested_function(); + /* check results here */ + + /* failing with EAGAIN */ + edg_wll_RegisterTestLogging(fail_EAGAIN_callback); + tested_function(); + /* check results here */ +} + +The consumer API (QueryEvents, QueryListener) fake implementations +prepare some result set which is returned to the caller. The callback +function may also adjust this set for particular purposes of the unit test. + +List of the callbacks and registering functions: + + 1) cosumer API + + typedef int (edg_wll_QueryEvents_cb_f) + (edg_wll_Context context, edg_wll_Event **events); + typedef int (edg_wll_QueryListener_cb_f) + (edg_wll_Context context, char **host, uint16_t *port); + + int edg_wll_RegisterTestQueryEvents(edg_wll_QueryEvents_cb_f *cb); + int edg_wll_RegisterTestQueryListener(edg_wll_QueryListener_cb_f *cb); + + 2) producer API + + typedef int (edg_wll_Logging_cb_f)(edg_wll_Context context); + + int edg_wll_RegisterTestLogging(edg_wll_Logging_cb_f *cb); + int edg_wll_RegisterTestLoggingProxy(edg_wll_Logging_cb_f *cb); + + +It possible to unregister registered callbacks using following functions: + + void edg_wll_UnregisterTestQueryEvents(); + void edg_wll_UnregisterTestQueryListener(); + void edg_wll_UnregisterTestLogging(); + void edg_wll_UnregisterTestLoggingProxy(); + + +Library name is libglite_lb_client_fake_gcc32dbg[pthr].so. It is built +in the org.glite.lb.client module, staged (so that it is available +for WMS unit tests run during the build process) but currenlty +neither installed nor included in RPM. + +Unit test programs should linked with this library instead of the original +libglite_lb_client_gcc32dbg[pthr].so. You can find examples of fake library +usage in org.glite.lb.client. The Makefile target 'fake' builds these examples. +There is no ant equivalent, hence the following procedure is required: + + cd org.glite.lb.client + ant init + cd build + make fake + + +* TODO (MATOUCI): v examples/ musi byt jednak priklady, ktere se linkuji s normalni +* knihovnou a funguji plnohodnotne dle ocekavani, a navic neco jako +* fake_job_log, ktery bude prikladem unittestu (opravdu s pouzitim cppUnitu +* atd.) nejake funkce z jinak opravdoveho job_log (asi bude treba ji +* pro tyto ucely vytahnout z main()u). + +In the example examples/job_log.c is showed how to use callbacks and their +registration. Examples examples/job_reg.c and src/logevent.c are original L&B +examples which are just linked with the fake library too. -- 1.8.2.3