DeeSharedModel

## DeeSharedModel DeeSharedModel — A DeeModel that can synchronize with other DeeSharedModel objects across D-Bus. |

## Synopsis

    #include <dee.h>

    #define             DEE_SHARED_MODEL_DBUS_IFACE
    struct              DeeSharedModel;
    enum                DeeSharedModelAccessMode;
    struct              DeeSharedModelClass;
    enum                DeeSharedModelError;
    guint               dee_shared_model_flush_revision_queue
                                                            (DeeSharedModel *self);
    DeePeer *           dee_shared_model_get_peer           (DeeSharedModel *self);
    const gchar *       dee_shared_model_get_swarm_name     (DeeSharedModel *self);
    gboolean            dee_shared_model_is_leader          (DeeSharedModel *self);
    gboolean            dee_shared_model_is_synchronized    (DeeSharedModel *self);
    DeeModel *          dee_shared_model_new                (const gchar *name);
    DeeModel *          dee_shared_model_new_for_peer       (DeePeer *peer);
    DeeModel *          dee_shared_model_new_with_back_end  (const gchar *name,
                                                             DeeModel *back_end);

## Object Hierarchy

      GObject
       +----DeeSerializableModel
             +----DeeProxyModel
                   +----DeeSharedModel

      GEnum
       +----DeeSharedModelAccessMode

## Implemented Interfaces

DeeSharedModel implements DeeModel and DeeSerializable.

## Properties

      "access-mode"              DeeSharedModelAccessMode  : Read / Write / Construct Only
      "flush-mode"               DeeSharedModelFlushMode  : Read / Write
      "peer"                     DeePeer*              : Read / Write / Construct Only
      "synchronized"             gboolean              : Read

## Signals

      "begin-transaction"                              : Run Last
      "end-transaction"                                : Run Last

## Description

DeeSharedModel is created with a name (usually namespaced and unique to your program(s)) which is used to locate other DeeSharedModels created with the same name through D-Bus, and will keep synchronized with them.

This allows to you build MVC programs with a sane model API, but have the controller (or multiple views) in a separate process.

Before you modify the contents of the shared model it is important that you wait for the model to synchronize with its peers. The normal way to do this is to wait for the "notify::synchronized" signal.

## Details

### DEE_SHARED_MODEL_DBUS_IFACE

    #define DEE_SHARED_MODEL_DBUS_IFACE "com.canonical.Dee.Model"

String constant defining the name of the DBus Model interface.

### struct DeeSharedModel

    struct DeeSharedModel;

All fields in the DeeSharedModel structure are private and should never be accessed directly

### enum DeeSharedModelAccessMode

    typedef enum {
      DEE_SHARED_MODEL_ACCESS_MODE_WORLD_WRITABLE,
      DEE_SHARED_MODEL_ACCESS_MODE_LEADER_WRITABLE
    } DeeSharedModelAccessMode;

Enumeration defining behavior of the model with regards to writes from other peers in the swarm.

`DEE_SHARED_MODEL_ACCESS_MODE_WORLD_WRITABLE` |
`DEE_SHARED_MODEL_ACCESS_MODE_LEADER_WRITABLE` |

### struct DeeSharedModelClass

    struct DeeSharedModelClass {
    };

### enum DeeSharedModelError

    typedef enum {
      DEE_SHARED_MODEL_ERROR_LEADER_INVALIDATED
    } DeeSharedModelError;

`DEE_SHARED_MODEL_ERROR_LEADER_INVALIDATED` |

### dee_shared_model_flush_revision_queue ()

    guint               dee_shared_model_flush_revision_queue
                                                            (DeeSharedModel *self);

Expert: All changes to `self` that has not yet been propagated to the peer models are send. If you also want to block the mainloop until all the underlying transport streams have been flushed use `dee_shared_model_flush_revision_queue_sync()`.

Normally DeeSharedModel collects changes to `self` into batches and sends them automatically to all peers. You can use this call to provide fine grained control of exactly when changes to `self` are synchronized to its peers. This may for example be useful to improve the interactivity of your application if you have a model-process which intermix small and light changes with big and expensive changes. Using this call you can make sure the model-process dispatches small changes more aggresively to the view-process, while holding on to the expensive changes a bit longer.

`self` : | The shared model to flush the revision queue on
Returns : | The number of revisions flushed.

### dee_shared_model_get_peer ()

    DeePeer *           dee_shared_model_get_peer           (DeeSharedModel *self);

Convenience function for accessing the "peer" property

`self` : | The model to get the DeePeer for
Returns : | The DeePeer used to interact with the peer models. [transfer none]

### dee_shared_model_get_swarm_name ()

    const gchar *       dee_shared_model_get_swarm_name     (DeeSharedModel *self);

Convenience function for accessing the "swarm-name" property of the DeePeer defined in the "peer" property.

`self` : | The model to get the name for
Returns : | The name of the swarm this model synchrnonizes with

### dee_shared_model_is_leader ()

    gboolean            dee_shared_model_is_leader          (DeeSharedModel *self);

Check if the model is the swarm leader. This is a convenience function for accessing the "peer" property and checking if it's the swarm leader.

`self` : | The model to inspect
Returns : | The value of `dee_peer_is_swarm_leader()` for the DeePeer used by this shared model

### dee_shared_model_is_synchronized ()

    gboolean            dee_shared_model_is_synchronized    (DeeSharedModel *self);

Check if the model is synchronized with its peers. Before modifying a shared model in any way (except `dee_model_set_schema()`) you should wait for it to become synchronized. This is normally done by waiting for the "notify::synchronized" signal.

This method is purely a convenience function for accessing the "synchronized" property.

`self` : | The model to inspect
Returns : | The value of the :synchronized property

### dee_shared_model_new ()

    DeeModel *          dee_shared_model_new                (const gchar *name);

Create a new empty shared model without any column schema associated. The column schema will be set in one of two ways: firstly you may set it manually with `dee_model_set_schema()` or secondly it will be set once the first rows are exchanged with a peer model.

A DeeSharedModel with a schema manually set has to be created before creating more DeeSharedModel with the same `name`.

A shared model created with this constructor will store row data in a suitably picked memory backed model.

`name` : | A well known name to publish this model under. Models sharing this name will synchronize with each other
Returns : | a new DeeSharedModel. [transfer full][type DeeSharedModel]

### dee_shared_model_new_for_peer ()

    DeeModel *          dee_shared_model_new_for_peer       (DeePeer *peer);

Create a new empty shared model without any column schema associated. The column schema will be set in one of two ways: firstly you may set it manually with `dee_model_set_schema()` or secondly it will be set once the first rows are exchanged with a peer model.

A DeeSharedModel with a schema manually set has to be created before creating more DeeSharedModel with the same `name`.

A shared model created with this constructor will store row data in a suitably picked memory backed model.

`peer` : | A DeePeer instance. [transfer full]
Returns : | a new DeeSharedModel. [transfer full][type DeeSharedModel]

### dee_shared_model_new_with_back_end ()

    DeeModel *          dee_shared_model_new_with_back_end  (const gchar *name,
                                                             DeeModel *back_end);

Create a new shared model storing all data in `back_end`.

The model will start synchronizing with peer models as soon as possible and the "synchronized" property will be set once finished.

`name` : | A well known name to publish this model under. Models sharing this name will synchronize with each other. [transfer none]
`back_end` : | The DeeModel that will actually store the model data. Ownership of the ref to `back_end` is transfered to the shared model. [transfer full]
Returns : | a new DeeSharedModel. [transfer full][type DeeSharedModel]

## Property Details

### The `"access-mode"` property

      "access-mode"              DeeSharedModelAccessMode  : Read / Write / Construct Only

Enumeration defining behavior of this model when trying to write to it.

Setting this to DEE_SHARED_MODEL_ACCESS_MODE_LEADER_WRITABLE is useful when one process is considered an "owner" of a model and all the other peers are supposed to only synchronize it for reading.

See also DeePeer:swarm-owner property to ensure ownership of a swarm.

Default value: DEE_SHARED_MODEL_ACCESS_MODE_WORLD_WRITABLE

### The `"flush-mode"` property

      "flush-mode"               DeeSharedModelFlushMode  : Read / Write

Enumeration defining the flushing behavior.

Setting this to DEE_SHARED_MODEL_FLUSH_MODE_MANUAL will disable automatic flushing that usually happens when the application's main event loop is idle. Automatic flushing should be primarily disabled when a shared model is used from multiple threads, or when not using GMainLoop. When disabled, `dee_shared_model_flush_revision_queue()` needs to be called explicitely.

Default value: DEE_SHARED_MODEL_FLUSH_MODE_AUTOMATIC

### The `"peer"` property

      "peer"                     DeePeer*              : Read / Write / Construct Only

The DeePeer that this model uses to connect to the swarm

### The `"synchronized"` property

      "synchronized"             gboolean              : Read

Boolean property defining whether or not the model has synchronized with its peers (if any) yet.

You should not modify a DeeSharedModel that is not synchronized. Before modifying the model in any way (except calling `dee_model_set_schema()`) you should wait for it to become synchronized.

Default value: FALSE

## Signal Details

### The `"begin-transaction"` signal

    void                user_function                      (DeeSharedModel *model,
                                                            guint64         begin_seqnum,
                                                            guint64         end_seqnum,
                                                            gpointer        user_data)         : Run Last

Emitted right before a remote transaction will be committed to the model.

`model` : | The shared model the signal is emitted on
`begin_seqnum` : | The seqnum the model has now
`end_seqnum` : | The seqnum the model will have after the transaction is applied
`user_data` : | user data set when the signal handler was connected.

### The `"end-transaction"` signal

    void                user_function                      (DeeSharedModel *model,
                                                            guint64         begin_seqnum,
                                                            guint64         end_seqnum,
                                                            gpointer        user_data)         : Run Last

Emitted right after a remote transaction has been committed to the model.

`model` : | The shared model the signal is emitted on
`begin_seqnum` : | The seqnum the model had before the transaction was applied
`end_seqnum` : | The seqnum the model has now
`user_data` : | user data set when the signal handler was connected.