InfAdoptedSession

InfAdoptedSession — Session handling concurrency control via the adOPTed algorithm.

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

InfAdoptedAlgorithm * algorithm Read
InfIo * io Read / Write / Construct Only
guint max-total-log-size Read / Write / Construct Only

Signals

gboolean check-request Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── InfSession
        ╰── InfAdoptedSession

Implemented Interfaces

InfAdoptedSession implements InfCommunicationObject.

Includes

#include <libinfinity/adopted/inf-adopted-session.h>

Description

InfAdoptedSession handles concurrency control with an InfAdoptedAlgorithm on top of a InfSession. It takes care of sending all necessary information to joining users, receives requests from the network (passing them to InfAdoptedAlgorithm) and transfers local requests to the other users. It also makes sure to periodically send the state the local host is in to other uses even if the local users are idle (which is required for others to cleanup their request logs and request caches).

Functions

inf_adopted_session_get_io ()

InfIo *
inf_adopted_session_get_io (InfAdoptedSession *session);

Returns the InfIo object of session .

Parameters

session

A InfAdoptedSession.

 

Returns

A InfIo.

[transfer none]


inf_adopted_session_get_algorithm ()

InfAdoptedAlgorithm *
inf_adopted_session_get_algorithm (InfAdoptedSession *session);

Returns the InfAdoptedAlgorithm object of session . Returns NULL if session has status INF_SESSION_PRESYNC or INF_SESSION_SYNCHRONIZING because there the algorithm object is not yet created before successful synchronization.

Parameters

session

A InfAdoptedSession.

 

Returns

A InfAdoptedAlgorithm, or NULL.

[transfer none]


inf_adopted_session_broadcast_request ()

void
inf_adopted_session_broadcast_request (InfAdoptedSession *session,
                                       InfAdoptedRequest *request);

Sends a request to all subscribed connections. The request should originate from a call to inf_adopted_algorithm_generate_request(), with session 's InfAdoptedAlgorithm.

Parameters

session

A InfAdoptedSession.

 

request

A InfAdoptedRequest obtained from session 's algorithm.

 

inf_adopted_session_undo ()

void
inf_adopted_session_undo (InfAdoptedSession *session,
                          InfAdoptedUser *user,
                          guint n);

This is a shortcut for creating n undo requests and broadcasting them. If n > 1 then this is also more efficient.

Parameters

session

A InfAdoptedSession.

 

user

A local InfAdoptedUser.

 

n

The number of undo requests to issue.

 

inf_adopted_session_redo ()

void
inf_adopted_session_redo (InfAdoptedSession *session,
                          InfAdoptedUser *user,
                          guint n);

This is a shortcut for creating n redo requests and broadcasting them. If n > 1 then this is also more efficient.

Parameters

session

A InfAdoptedSession.

 

user

A local InfAdoptedUser.

 

n

The number of redo requests to issue.

 

inf_adopted_session_read_request_info ()

gboolean
inf_adopted_session_read_request_info (InfAdoptedSession *session,
                                       xmlNodePtr xml,
                                       InfAdoptedStateVector *diff_vec,
                                       InfAdoptedUser **user,
                                       InfAdoptedStateVector **time,
                                       xmlNodePtr *operation,
                                       GError **error);

This function reads common information such as the state vector the request was made and the user that made the request from XML. It is most likely to be used by implementations of the xml_to_request virtual function.

Parameters

session

A InfAdoptedSession.

 

xml

The XML to read the data from.

 

diff_vec

The reference vector of the time vector of the request, or NULL.

 

user

Location to store the user of the request, or NULL.

[out][transfer none][allow-none]

time

Location to store the state the request was made, or NULL.

[out][transfer full][allow-none]

operation

Location to store the operation of the request, or NULL.

[out][transfer none][allow-none]

error

Location to place an error, if any.

 

Returns

TRUE if the data could be read successfully, FALSE if the XML request does not contain valid request data, in which case error is set.


inf_adopted_session_write_request_info ()

void
inf_adopted_session_write_request_info
                               (InfAdoptedSession *session,
                                InfAdoptedRequest *request,
                                InfAdoptedStateVector *diff_vec,
                                xmlNodePtr xml,
                                xmlNodePtr operation);

This function writes common data from request , such as the user that issued the request and the state in which the request was made into xml . If diff_vec is given, then the state is written as a diff to this vector, see inf_adopted_state_vector_to_string_diff(). Deserializing this data again (via inf_adopted_session_read_request_info()) requires the same diff_vec then.

This function is most likely to be used by implementations of the request_to_xml virtual function.

Parameters

session

A InfAdoptedSession.

 

diff_vec

A reference state vector, or NULL.

 

request

The InfAdoptedRequest whose info to write.

 

xml

The XML node to write the data into.

 

operation

An XML node representing the operation of the request, or NULL.

 

Types and Values

enum InfAdoptedSessionError

Error codes for InfAdoptedSession. These only occur when invalid requests are received from the network.

Members

INF_ADOPTED_SESSION_ERROR_NO_SUCH_USER

The "user" field in a request message does not contain a valid user ID.

 

INF_ADOPTED_SESSION_ERROR_MISSING_OPERATION

A request message does not contain an operation.

 

INF_ADOPTED_SESSION_ERROR_INVALID_REQUEST

A request in a synchronized request log is invalid. Invalid means that it is not the request that was issued after the previous request in the log, or that it is an Undo or Redo request without a request to Undo or Redo, respectively.

 

INF_ADOPTED_SESSION_ERROR_MISSING_STATE_VECTOR

A synchronized user does not contain that the state that user currently is in.

 

INF_ADOPTED_SESSION_ERROR_FAILED

No further specified error code.

 

struct InfAdoptedSession

struct InfAdoptedSession;

InfAdoptedSession is an opaque data type. You should only access it via the public API functions.


struct InfAdoptedSessionClass

struct InfAdoptedSessionClass {
  InfAdoptedRequest*(*xml_to_request)(InfAdoptedSession* session,
                                      xmlNodePtr xml,
                                      InfAdoptedStateVector* diff_vec,
                                      gboolean for_sync,
                                      GError** error);

  void(*request_to_xml)(InfAdoptedSession* session,
                        xmlNodePtr xml,
                        InfAdoptedRequest* request,
                        InfAdoptedStateVector* diff_vec,
                        gboolean for_sync);

  /* Signals */

  gboolean(*check_request)(InfAdoptedSession* session,
                           InfAdoptedRequest* request,
                           InfAdoptedUser* user);
};

Virtual functions and default signal handlers for InfAdoptedSession.

Members

xml_to_request ()

Virtual function to deserialize an InfAdoptedRequest from XML. The implementation of this function can use inf_adopted_session_read_request_info() to read the common info.

 

request_to_xml ()

Virtual function to serialize an InfAdoptedRequest to XML. This function should add properties and children to the given XML node. At might use inf_adopted_session_write_request_info() to write the common info.

 

check_request ()

Default signal handler of the InfAdoptedSession::check-request signal.

 

Property Details

The “algorithm” property

  “algorithm”                InfAdoptedAlgorithm *

The adOPTed algorithm used for translating incoming requests.

Owner: InfAdoptedSession

Flags: Read


The “io” property

  “io”                       InfIo *

The IO object used for timeouts.

Owner: InfAdoptedSession

Flags: Read / Write / Construct Only


The “max-total-log-size” property

  “max-total-log-size”       guint

The maximum number of requests to keep in all user's logs.

Owner: InfAdoptedSession

Flags: Read / Write / Construct Only

Default value: 2048

Signal Details

The “check-request” signal

gboolean
user_function (InfAdoptedSession *session,
               InfAdoptedRequest *request,
               InfAdoptedUser    *user,
               gpointer           user_data)

This signal is emitted whenever the session received a request from a non-local user. It is used to decide whether the request should be processed or not. Note that generally not processing a request results is loss of synchronization, since other hosts might process the request. Only if the same condition can be applied on all sites a request should be rejected. Another possibility is to reject a request at a central host before it gets distributed to all other clients. If there is one signal handler returning TRUE the request is rejected, i.e. only if all signal handlers return FALSE it is accepted.

Parameters

session

The InfAdoptedSession which is about to process a request.

 

request

The request to be processed.

 

user

The user who issued the request.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

InfSession, InfAdoptedAlgorithm