app_model.h

/*
 * The MIT License (MIT)
 *
 * Copyright (c) 2015 Microsoft Corporation
 * 
 * -=- Robust Distributed System Nucleus (rDSN) -=- 
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */

/*
 * Description:
 *     application model in rDSN
 *
 * Revision history:
 *     Mar., 2015, @imzhenyu (Zhenyu Guo), first version
 *     xxxx-xx-xx, author, fix bug about xxx
 */

# pragma once

# include <dsn/c/api_common.h>

# ifdef __cplusplus
namespace dsn { class service_app; }
extern "C" {
# endif


typedef void*       (*dsn_app_create)(
    const char* app_name,
    dsn_gpid    id
    );

typedef dsn_error_t(*dsn_app_start)(
    void*  app,
    int    argc,
    char** argv
    );

typedef dsn_error_t(*dsn_app_destroy)(
    void* app,
    bool  cleanup
    );

typedef void(*dsn_framework_rpc_request_handler)(
    void*         app,
    dsn_gpid      gpid,
    bool          is_write_operation,
    dsn_message_t request
    );

struct dsn_app_learn_state
{
    int     total_learn_state_size; 
    int64_t from_decree_excluded;   
    int64_t to_decree_included;     
    int     meta_state_size;        
    int     file_state_count;       
    void*   meta_state_ptr;         
    const char** files;             
};


enum dsn_chkpt_apply_mode
{
    DSN_CHKPT_COPY,  
    DSN_CHKPT_LEARN  
};

typedef void(*dsn_app_on_batched_write_requests)(
    void*           app,
    int64_t         decree,
    dsn_message_t*  requests,
    int             request_count
    );

typedef int(*dsn_app_get_physical_error)(
    void* app
    );

typedef dsn_error_t(*dsn_app_sync_checkpoint)(
    void*   app,
    int64_t last_decree
    );

typedef dsn_error_t(*dsn_app_async_checkpoint)(
    void*   app,
    int64_t last_decree
    );

typedef int64_t(*dsn_app_get_last_checkpoint_decree)(
    void*  app
    );

typedef dsn_error_t(*dsn_app_prepare_get_checkpoint)(
    void* app,
    void* request_buffer,
    int   capacity,
    /*out*/ int* used_size
    );

typedef dsn_error_t(*dsn_app_get_checkpoint)(
    void*   app,
    int64_t learn_start_decree,
    int64_t local_last_decree,
    void*   learn_request,
    int     learn_request_size,
    dsn_app_learn_state* learn_state_buffer,
    int                  capacity
    );

typedef dsn_error_t(*dsn_app_apply_checkpoint)(
    void*                 app,
    dsn_chkpt_apply_mode  mode,
    int64_t               local_last_decree,
    const dsn_app_learn_state* learn_state
    );

# define DSN_APP_MASK_APP        0x01 
# define DSN_APP_MASK_FRAMEWORK  0x02 


typedef dsn_error_t(*dsn_app_bridge_t)(int, const char**);

# pragma pack(push, 4)

typedef union dsn_app_callbacks
{
    dsn_app_create placeholder[DSN_MAX_CALLBAC_COUNT];
    struct app_callbacks
    {
        dsn_app_on_batched_write_requests   on_batched_write_requests;
        dsn_app_get_physical_error          get_physical_error;
        dsn_app_sync_checkpoint             sync_checkpoint;
        dsn_app_async_checkpoint            async_checkpoint;
        dsn_app_get_last_checkpoint_decree  get_last_checkpoint_decree;
        dsn_app_prepare_get_checkpoint      prepare_get_checkpoint;
        dsn_app_get_checkpoint              get_checkpoint;
        dsn_app_apply_checkpoint            apply_checkpoint;
    } calls;    
} dsn_app_callbacks;


typedef struct dsn_app
{
    uint64_t        mask; 
    char            type_name[DSN_MAX_APP_TYPE_NAME_LENGTH]; 

    struct layer1_callbacks
    {
        dsn_app_create  create;  
        dsn_app_start   start;   
        dsn_app_destroy destroy; 
    } layer1;    

    struct
    {
        struct layer2_framework_callbacks
        {
            dsn_framework_rpc_request_handler on_rpc_request;
        } frameworks;

        dsn_app_callbacks apps;
    } layer2;    
} dsn_app;
# pragma pack(pop)

# pragma pack(push, 4)

typedef struct dsn_app_info
{
    //
    // app information
    //
    union {
        void* app_context_ptr;                
# ifdef __cplusplus
        ::dsn::service_app *app_ptr_cpp;
# endif
    } app;
    
    int   app_id;                             
    int   index;                              
    char  role[DSN_MAX_APP_TYPE_NAME_LENGTH]; 
    char  type[DSN_MAX_APP_TYPE_NAME_LENGTH]; 
    char  name[DSN_MAX_APP_TYPE_NAME_LENGTH]; 
    char  data_dir[DSN_MAX_PATH];             
    dsn_address_t primary_address;            
} dsn_app_info;
# pragma pack(pop)

extern DSN_API bool      dsn_register_app(dsn_app* app_type);

extern DSN_API bool      dsn_get_app_callbacks(const char* name, /* out */ dsn_app_callbacks* callbacks);

extern DSN_API bool      dsn_mimic_app(
                            const char* app_name, 
                            int index 
                            );

extern DSN_API bool      dsn_run_config(
                            const char* config, 
                            bool sleep_after_init DEFAULT(false)
                            );

extern DSN_API void dsn_run(int argc, char** argv, bool sleep_after_init DEFAULT(false));

NORETURN extern DSN_API void dsn_exit(int code);

extern DSN_API int  dsn_get_all_apps(/*out*/ dsn_app_info* info_buffer, int count);

extern DSN_API bool dsn_get_current_app_info(/*out*/ dsn_app_info* app_info);

extern DSN_API dsn_app_info* dsn_get_app_info_ptr(dsn_gpid gpid DEFAULT(dsn_gpid{ 0 }));

extern DSN_API const char* dsn_get_app_data_dir(dsn_gpid gpid DEFAULT(dsn_gpid{ 0 }));

extern DSN_API void dsn_app_loader_signal();

extern DSN_API void dsn_app_loader_wait();

# ifdef __cplusplus
}
# endif