/*

* Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef CPIX_CPIX_ASYNC_H

#define CPIX_CPIX_ASYNC_H

#include "cpixidxdb.h"

#include "cpixsearch.h"

/****************************************************************

 *

 *    O V E R V I E W

 *

 * CPix API for some asynchronous API operations (not all sync

 * operations have async conterparts). All async operations are

 * semantically equivalent to their synchronous brethren, they just

 * happen to be asynchronous. For sample function

 *

 * "int cpix_Foo_bar(cpix_Foo * thisFoo,

 *                   int        arg);"

 *

 * The following async function will be created:

 *

 * "cpix_JobId cpix_Foo_asyncBar(cpix_Foo * thisFoo,

 *                               int        arg,

 *                               void     * cookie,

 *                               void    (* callback)(void *, cpix_JobId));"

 *

 * Argument thisFoo has the same meaning in both the sync and the

 * async version: the operation "bar(int)" is performed on that

 * object. If there is an error during creating the async job itself,

 * the error is reported on thisFoo.

 *

 * Hypothetical argument "arg" has the exact same meaning: some argument

 * for "bar(int)".

 *

 * Argument "cookie" is some client specific data that the client

 * wants to see as an argument given to the callback in the async

 * version - to be able to identify the request.

 *

 * Argument "callback" is a callback function that can conceptually

 * give kick the caller with the given cookie and the job id that was

 * allocated for the job. The arguments given to the callback will be

 * the cookie and the job id that has been completed. The callback

 * should be doing no serious processing of the results, only some

 * administrative work to signal some party to collect the results.

 *

 * Normally, once the asyncBar has kicked the callback, the client can

 * come and collect the results of the async operation 'bar', like

 *

 * int cpix_Foo_asyncBarResults(cpix_Foo   * thisFoo,

 *                              cpix_JobId   jobId);

 *

 * Where the return value is given there as well as error status is

 * communicated through thisFoo. For all (non-cancellable) async

 * functions calls, there must be a corresponding result-collection

 * call. Such result collection call must be done only after the

 * callback has been called by the worker. DO NOT collect the results

 * as part of the callback.

 *

 * NOTE, that the job-creation itself may fail, that is, the call to

 * cpix_Foo_asuyncBar may report error on thisFoo. In that case the

 * job was not created, there is no need to cancel or collect the

 * results.

 *

 * Some async operations are cancellable.

 *

 * Calling cancel on an object (cpix_IdxDb*, cpix_IdxSearcher* or

 * cpix_Hits*) will guarantee that the callback is not called for the

 * client object once the cancel function returns. For all cancellable

 * async function calls, there must be either a cancel or a

 * result-collection call. Cancel operations can be called any time,

 * even before the callback has been called by the worker.

 *

 * Instances of cpix_IdxDb and cpix_IdxSearcher should not be deleted

 * before either cancel() or cpix_XXX_asyncXXXResults() is

 * called. Argument instances like cpix_Document, cpix_Analyzer,

 * cpix_Query can be immediately released by the client call.

 *

 * Any argument that is an object (like cpix_Document*, const

 * wchar_t*, ...) can be immediately discarded by the client after a

 * call to cpix_XXX_cancelMMM(): those instances are either cloned or

 * have reference counted lifetime management.

 *

 * NOTE:

 *

 * 1 Don't ever use the same cpix_IdxDb or cpix_IdxSearch instance

 *   from multiple threads. These objects themselves are not

 *   thread-safe.

 *

 * 2 You should be able to use different cpix_IdxDb instances that

 *   actually manage the same underlyng physical index volume - that

 *   should work.

 *

 * 3 Make absolutely certain that you clear the error status on

 *   cpix_Foo on all async operations (like cpix_Foo_asyncBar,

 *   cpix_foo_asyncBarResults, cpix_Foo_cancel()). Failure to do so

 *   may result in leaking error-status objects. (Obviously, you

 *   should check the error status on cpix_Foo anyway after all calls

 *   anyway.) To clear the error status, use macro cpix_ClearError

 *   from cpixerror.h.

 *

 * 4 If you use an async version of an operation, then you MUST use

 *   the async version of each operation where available.

 *

 *   That means that once you use (any of) this ASYNC api, you must

 *   never call any of these functions:

 *

 *     cpix_IdxDb_add,

 *     cpix_IdxDb_deleteDocuments,

 *     cpix_IdxDb_update,

 *     cpix_IdxDb_flush,

 *     cpix_IdxDb_doHousekeeping,

 *     cpix_IdxDb_search,

 *     cpix_IdxSearcher_search,

 *     cpix_Hits_doc.

 *

 *

 * RULES concerning cancel(), cpix_XXX_asyncXXXResults()

 * (results(), for short) and callback():

 *

 * 1 Once cancel() returns, callback() will not occur.

 *

 * 2 There must be exactly one of these calls: cancel() and

 *   results(). There can be no duplicate cancels() or calling

 *   results() after cancel() has been called.

 *

 * 3 results() give back results, possibly transferring ownership of

 *   resulting instances to the client, but cancel() makes sure that

 *   all resources related to the job are released.

 *

 * 4 Therefore once a call to cancel() has been made, you must not

 *   attempt to try to collect the results by calling result().

 *

 * 5 callback() may occur any time before cancel() returns. It can

 *   happen that the client is already in the cancel() call, and

 *   during that time callback() happens. In that case, the client

 *   must clear the called back status, and make sure that the

 *   results() are not called by mistake.

 */

#ifdef __cplusplus

extern "C" {

#endif

    /**

     * Every asynchronous job will have an ID allocated, one must

     * collect the result of the job / cancel it referring to that ID.

     */

    typedef size_t cpix_JobId;

    /**

     * Callback type to signal the client that the operation has

     * completed. Normally, after the callback, the client would

     * proceed to collect the error status and possible return values.

     */

    typedef void cpix_AsyncCallback(void       * cookie,

                                    cpix_JobId   jobId);

    /**

     * Each cancel operation returns how the cancel request was

     * handled. Useful for development purposes (logging and observing

     * clien behaviour) but has no real benefit for end user.

     */

    enum cpix_CancelAction_

        {

            /**

             * If the cancel request while the request was still

             * pending in the job queue - the job was killed even

             * before it could have started.

             */

            cpix_CANCEL_SHALLOW,

            /**

             * The cancel request cam exactly while the job was being

             * executed - the job was interrupted and killed that way.

             */

            cpix_CANCEL_DEEP,

            /**

             * The cancel request came after the job was already done.

             */

            cpix_CANCEL_JOBDONE,

            /**

             * Unknown error during cancel.

             */

            cpix_CANCEL_ERROR

        };

    typedef cpix_CancelAction_ cpix_CancelAction;

    /***************************************************************

     *

     *    A S Y N C   F U N C T I O N S

     *

     */

    /**

     * Corresponding sync function: cpix_IdxDb_add (cpixidxdb.h), see

     * overview and description for params 'thisIdxDb', 'document' and

     * 'analyzer' there. Error status is signaled on thisIdxDb right

     * away if the very creation of the asynchronous job has

     * failed. In that case, you can't collect the results of the

     * operation.

     *

     * For a general description of parameters 'cookie' and

     * 'callback', see the OVERVIEW comment above.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_IdxDb_asyncAdd(cpix_IdxDb         * thisIdxDb,

                                   cpix_Document      * document,

                                   cpix_Analyzer      * analyzer,

                                   void               * cookie,

                                   cpix_AsyncCallback * callback);

    /**

     * Collects the results on the completed async add operation on

     * thisIdxDb. Error status of the job execution is signalled on

     * thisIdxDb.

     */

    void cpix_IdxDb_asyncAddResults(cpix_IdxDb * thisIdxDb,

                                    cpix_JobId   jobId);

    /**

     * Corresponding to sync function: cpix_IdxDb_deleteDocuments

     * (cpixidxdb.h), see overview and description for params 'thisIdxDb'

     * and 'docUid' there. Error status is signaled on thisIdxDb right

     * away if the very creation of the asynchronous job has

     * failed. In that case, you can't collect the results of the

     * operation.

     *

     * For a general description of parameters 'cookie' and

     * 'callback', see the OVERVIEW comment above.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_IdxDb_asyncDeleteDocuments(cpix_IdxDb         * thisIdxDb,

                                               const wchar_t      * docUid,

                                               void               * cookie,

                                               cpix_AsyncCallback * callback);

    /**

     * Collects the results on the completed async delete documents

     * operation on thisIdxDb. Error status of the job execution is

     * signalled on thisIdxDb.

     */

    int32_t cpix_IdxDb_asyncDeleteDocumentsResults(cpix_IdxDb * thisIdxDb,

                                                   cpix_JobId   jobId);

    /**

     * Corresponding sync function: cpix_IdxDb_update (cpixidxdb.h), see

     * overview and description for params 'thisIdxDb', 'document' and

     * 'analyzer' there. Error status is signaled on thisIdxDb right

     * away if the very creation of the asynchronous job has

     * failed. In that case, you can't collect the results of the

     * operation.

     *

     * For a general description of parameters 'cookie' and

     * 'callback', see the OVERVIEW comment above.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_IdxDb_asyncUpdate(cpix_IdxDb         * thisIdxDb,

                                      cpix_Document      * document,

                                      cpix_Analyzer      * analyzer,

                                      void               * cookie,

                                      cpix_AsyncCallback * callback);

    /**

     * Collects the results of the completed async update operation on

     * thisIdxDb. Error status of the job execution is signalled on

     * thisIdxDb.

     */

    void cpix_IdxDb_asyncUpdateResults(cpix_IdxDb * thisIdxDb,

                                       cpix_JobId   jobId);

    /**

     * Corresponding sync function: cpix_IdxDb_flush (cpixidxdb.h),

     * see overview and description for params 'thisIdxDb'. Error

     * status is signaled on thisIdxDb right away if the very creation

     * of the asynchronous job has failed. In that case, you can't

     * collect the results of the operation.

     *

     * For a general description of parameters 'cookie' and

     * 'callback', see the OVERVIEW comment above.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_IdxDb_asyncFlush(cpix_IdxDb         * thisIdxDb,

                                     void               * cookie,

                                     cpix_AsyncCallback * callback);

    /**

     * Collects the results of the completed flush operation on the

     * given thisIdxDb. Error status of the job execution is signalled

     * on thisIdxDb.

     */

    void cpix_IdxDb_asyncFlushResults(cpix_IdxDb * thisIdxDb,

                                      cpix_JobId   jobId);

    /**

     * Corresponding sync function: cpix_doHousekeeping (cpixinit.h),

     * see overview. This function is a "static"/"library" function,

     * that is, it does not have a "this" parameter, only cpix_Result

     * that can tell if the creation of async job has failed. On

     * failure of creating the job, you can't collect the results of

     * the operation.

     *

     * For a general description of parameters 'cookie' and

     * 'callback', see the OVERVIEW comment above.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_asyncDoHousekeeping(cpix_Result        * result,

                                        void               * cookie,

                                        cpix_AsyncCallback * callback);

    /**

     * Collects the results of the completed doHousekeeping

     * operation. Error status of job execution is signalled on

     * result.

     */

    void cpix_asyncDoHousekeepingResults(cpix_Result       * result,

                                         cpix_JobId          jobId);

    /**

     * TODO: review this comment "Error status is NOT signaled on thisIdxDb"

     * Corresponding sync function: cpix_IdxDb_search (cpixidxdb.h),

     * see overview and description for params 'thisIdxDb' and

     * 'query'. Error status is NOT signaled on thisIdxDb. Error

     * status is signaled on thisIdxDb right away if the very creation

     * of the asynchronous job has failed. In that case, you can't

     * cancel or collect the results of the operation.

     *

     * For a general description of parameters 'cookie' and

     * 'callback', see the OVERVIEW comment above.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_IdxDb_asyncSearch(cpix_IdxDb         * thisIdxDb,

                                      cpix_Query         * query,

                                      void               * cookie,

                                      cpix_AsyncCallback * callback);

    /**

     * Collects the results on the completed async search operation on

     * thisIdxDb. Error status of the job execution is signalled on

     * thisIdxDb.

     */

    cpix_Hits * cpix_IdxDb_asyncSearchResults(cpix_IdxDb * thisIdxDb,

                                              cpix_JobId   jobId);

    /**

     * Cancels the outstanding async operation on the given index

     * database. Once this method has returned, no callbacks will be

     * called for that object (there may be callbacks before this

     * returns).

     *

     * @returns the way the cancel was handled

     */

    cpix_CancelAction cpix_IdxDb_cancelSearch(cpix_IdxDb * thisIdxDb,

                                              cpix_JobId   jobId);

    /**

     * Corresponding sync function: cpix_IdxSearcher_search

     * (cpixsearch.h), see overview and description for params

     * 'thisIdxSearcher' and 'query'. Error status is signaled on

     * thisIdxDb right away if the very creation of the asynchronous

     * job has failed. In that case, you can't cancel or collect the

     * results of the operation.

     *

     * For a general description of parameters 'cookie' and

     * 'callback', see the OVERVIEW comment above.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_IdxSearcher_asyncSearch(cpix_IdxSearcher   * thisIdxSearcher,

                                            cpix_Query         * query,

                                            void               * cookie,

                                            cpix_AsyncCallback * callback);

    /**

     * Collects the results on the completed async search operation on

     * thisIdxSearcher. Error status of the job execution is signalled

     * on thisIdxDb.

     *

     * Ownership of the hits is transferred to the client.

     */

    cpix_Hits * 

    cpix_IdxSearcher_asyncSearchResults(cpix_IdxSearcher * thisIdxsearcher,

                                        cpix_JobId         jobId);

    /**

     * Cancels the outstanding async search operation on the given

     * searcher. Once this method has returned, no callbacks will be

     * called for that object (there may be callbacks before this

     * returns).

     *

     * @returns the way the cancel was handled

     */

    cpix_CancelAction 

    cpix_IdxSearcher_cancelSearch(cpix_IdxSearcher * thisIdxSearcher,

                                  cpix_JobId         jobId);

    /**

     * Corresponding to the function: cpix_Hits_doc

     * (cpixsearch.h). See overview and description for params

     * 'thisHits', 'index' and 'target'. Error status is signaled on

     * thisHits right away if the very creation of the asynchronous

     * job has failed. In that case, you can't cancel or collect the

     * results of the operation.

     *

     * For generation description of parameters 'cookie' and

     * 'callback' see the OVERVIEW comment above.

     *

     * Document retrieval may trigger re-committing the original

     * search, if the underlying indexes were modified, hence the need

     * for async version of this operation.

     *

     * NOTE: The semantics of param 'target' are almost exactly the

     * same as in the sync version: the wrapper is owned by the

     * client, the wrapped is owned by engine, hence this type of

     * signature.

     *

     * NOTE: However, there is one 

     *                          C R U C I A L

     *                                     difference between how

     * target document can be allocated. In the sync version it

     * can/should be a local variable, on the stack. But in the async

     * version, you MUST absolutely make certain that cpix_Document

     * instance target points to is not on the stack, but part of some

     * C++ class instance / C struct instance layout. This is because

     * while cpix_Hits_asycnDoc is cancellable, it only means that the

     * client has the right to not collect the results, but the

     * operation may (will) be completed, and therefore the place

     * target points to will be initialized as a cpix_Document. But,

     * by the time that happens, the client will have moved on, after

     * cancelling the operation, to do other stuff, which means that

     * callstack of the client will be MESSED UP. Hence, keep the

     * target document off the stack, somewhere in the layout of a

     * C/C++ object instance.

     *

     * @return the job id of the created job, if successful

     */

    cpix_JobId cpix_Hits_asyncDoc(cpix_Hits          * thisHits,

                                  int32_t              index,

                                  void               * cookie,

    /**

     * Collects the results of the completed async doc-retrieval

     * operation on thisHits. Error status of the job execution is

     * signalled on thisHits.

     */

    void cpix_Hits_asyncDocResults(cpix_Hits * thisHits,

                                   cpix_JobId  jobId);

    /**

     * Cancels the outstanding async search operation on the given

     * hits list. Once this method as has returned, no callbacks will

     * be called for that object (there may be callbacks before this

     * returns).

     *

     *

     * @returns the way the cancel was handled

     */

    cpix_CancelAction cpix_Hits_cancelDoc(cpix_Hits * thisHits,

                                          cpix_JobId  jobId);

#ifdef __cplusplus

} /* extern "C" */

#endif /* __cplusplus */