Infinity.AdoptedAlgorithm

g GObject.Object GObject.Object Infinity.AdoptedAlgorithm Infinity.AdoptedAlgorithm GObject.Object->Infinity.AdoptedAlgorithm

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class

new (user_table, buffer)

class

new_full (user_table, buffer, max_total_log_size)

can_redo (user)

can_undo (user)

cleanup ()

execute_request (request, apply)

generate_request (type, user, operation)

get_current ()

get_execute_request ()

translate_request (request, to)

Virtual Methods

Inherited:

GObject.Object (7)

do_begin_execute_request (user, request)

do_can_redo_changed (user, can_redo)

do_can_undo_changed (user, can_undo)

do_end_execute_request (user, request, translated_request, error)

Properties

Name

Type

Flags

Short Description

buffer

Infinity.Buffer

r/w/co

The buffer to apply operations to

buffer-modified-state

Infinity.AdoptedStateVector

r

The state in which the buffer is considered not being modified

current-state

Infinity.AdoptedStateVector

r

The state vector describing the current document state

max-total-log-size

int

r/w/co

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

user-table

Infinity.UserTable

r/w/co

The user table

Signals

Inherited:

GObject.Object (1)

Name

Short Description

begin-execute-request

This signal is emitted every time the algorithm executes a request, i.e.

can-redo-changed

This signal is emitted every time the can-redo state of a local user in algorithm's user table changed.

can-undo-changed

This signal is emitted every time the can-undo state of a local user in algorithm's user table changed.

end-execute-request

This signal is emitted after a request has been executed.

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent

GObject.Object

r

priv

object

r

Class Details

class Infinity.AdoptedAlgorithm(**kwargs)
Bases:

GObject.Object

Abstract:

No

Structure:

Infinity.AdoptedAlgorithmClass

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

classmethod new(user_table, buffer)
Parameters:
Returns:

A new Infinity.AdoptedAlgorithm.

Return type:

Infinity.AdoptedAlgorithm

Creates a Infinity.AdoptedAlgorithm.

classmethod new_full(user_table, buffer, max_total_log_size)
Parameters:

  • user_table (Infinity.UserTable) – The table of participating users.

  • buffer (Infinity.Buffer) – The buffer to apply operations to.

  • max_total_log_size (int) – The maxmimum number of operations to keep in all user’s request logs.

Returns:

A new Infinity.AdoptedAlgorithm.

Return type:

Infinity.AdoptedAlgorithm

Note that it is possible that request logs need to grow a bit larger than max_total_log_size in high-latency situations or when a user does not send status updates frequently. However, when all requests have been processed by all users, the sum of all requests in the logs is guaranteed to be lower or equal to this value.

Set to GObject.G_MAXUINT to disable limitation. In theory, this would allow everyone to undo every operation up to the first one ever made. In practise, this issues a huge amount of data that needs to be synchronized on user join and is too expensive to compute anyway.

The default value is 2048.

can_redo(user)
Parameters:

user (Infinity.AdoptedUser) – A local Infinity.AdoptedUser.

Returns:

True if Redo is possible, False otherwise.

Return type:

bool

Returns whether user can issue a redo request in the current state. Note that if user is non-local, then the result of this function does not depend on the current state but on the state that we know user is guaranteed to have reached. This is because user might still issue a Redo request even if the max-total-log-size is already exceeded if user does not know yet that it is exceeded.

can_undo(user)
Parameters:

user (Infinity.AdoptedUser) – A local Infinity.AdoptedUser.

Returns:

True if Undo is possible, False otherwise.

Return type:

bool

Returns whether user can issue an undo request in the current state. Note that if user is non-local, then the result of this function does not depend on the current state but on the state that we know user is guaranteed to have reached. This is because user might still issue an Undo request even if the max-total-log-size is already exceeded if user does not know yet that it is exceeded.

cleanup()

Removes requests in all users request logs which are no longer needed. This includes requests which cannot be undone or redone anymore due to the constraints of the Infinity.AdoptedAlgorithm :max-total-log-size property, and requests that every participant is guaranteed to have processed already.

This function can be called after every executed request to keep memory use to a minimum, or it can be called in regular intervals, or it can also be omitted if the request history should be preserved.

execute_request(request, apply)
Parameters:
Raises:

GLib.Error

Returns:

True on success or False on error.

Return type:

bool

This function transforms the given request such that it can be applied to the current document state and then applies it the buffer and adds it to the request log of the algorithm, so that it is used for future transformations of other requests.

If apply is False then the request is not applied to the buffer. In this case, it is assumed that the buffer is already modified, and that the request is made as a result from the buffer modification. This also means that the request must be applicable to the current document state, without requiring transformation.

In addition, the function emits the Infinity.AdoptedAlgorithm ::begin-execute-request and Infinity.AdoptedAlgorithm ::end-execute-request signals, and makes Infinity.AdoptedAlgorithm.get_execute_request() return request during that period.

This allows other code to hook in before and after request processing. This does not cause any loss of generality because this function is not re-entrant anyway: it cannot work when used concurrently by multiple threads nor in a recursive manner, because only when one request has been added to the log the next request can be translated, since it might need the previous request for the translation path and it needs to be translated to a state where the effect of the previous request is included so that it can consistently applied to the buffer.

There are also runtime errors that can occur if request execution fails. In this case the function returns False and error is set. Possible reasons for this include request being an Infinity.AdoptedRequestType.UNDO or Infinity.AdoptedRequestType.REDO request without there being an operation to undo or redo, or if the translated operation cannot be applied to the buffer. This usually means that the input request was invalid. However, this is not considered a programmer error because typically requests are received from untrusted input sources such as network connections. Note that there cannot be any runtime errors if apply is set to False. In that case it is safe to call the function with None error.

generate_request(type, user, operation)
Parameters:
Returns:

A new Infinity.AdoptedRequest. Free with GObject.Object.unref() when no longer needed.

Return type:

Infinity.AdoptedRequest

Creates a new request that can be applied to the current document state. The request is made by the given user. If operation is of type Infinity.AdoptedRequestType.DO, then operation specifies the operation to be performed. Otherwise, operation must be None.

To apply the effect of the request to the document, run Infinity.AdoptedAlgorithm.execute_request(). Note that even if the effect is already applied to the document, the function must still be called with the apply parameter set to False, so that the algorithm knows that the request has been applied.

get_current()
Returns:

A Infinity.AdoptedStateVector owned by self.

Return type:

Infinity.AdoptedStateVector

Returns the current vector time of self.

get_execute_request()
Returns:

The request that self is currently processing, or None. The return value must not be freed by the caller.

Return type:

Infinity.AdoptedRequest or None

Returns whether the algorithm is currently transforming a request to the current state and appling its state to the buffer. If it is the function is returning the request that was received and is currently being executed, other wise the function returns None. Note that the request execution is not re-entrant, i.e. two requests cannot be executed concurrently at the same time, or recursively.

translate_request(request, to)
Parameters:
Returns:

A new or cached Infinity.AdoptedRequest. Free with GObject.Object.unref() when no longer needed.

Return type:

Infinity.AdoptedRequest

Translates request so that it can be applied to the document at state to. request will not be modified but a new, translated request is returned instead.

There are several preconditions for this function to be called. to must be a reachable point in the state space. Also, requests can only be translated in forward direction, so request's vector time must be causally before (see Infinity.AdoptedStateVector.causally_before()) to.

do_begin_execute_request(user, request) virtual
Parameters:
do_can_redo_changed(user, can_redo) virtual
Parameters:
do_can_undo_changed(user, can_undo) virtual
Parameters:
do_end_execute_request(user, request, translated_request, error) virtual
Parameters:

Signal Details

Infinity.AdoptedAlgorithm.signals.begin_execute_request(adopted_algorithm, user, request)
Signal Name:

begin-execute-request

Flags:

RUN_LAST

Parameters:

This signal is emitted every time the algorithm executes a request, i.e. transforms it such that it can be applied to the current state, resolves undo/redo operations and applies the resulting operation to the buffer.

Infinity.AdoptedAlgorithm.signals.can_redo_changed(adopted_algorithm, user, can_undo)
Signal Name:

can-redo-changed

Flags:

RUN_LAST

Parameters:

This signal is emitted every time the can-redo state of a local user in algorithm's user table changed. The can-redo state defines whether user can generate a redo request (via Infinity.AdoptedAlgorithm.generate_request()) in the current situation, see also Infinity.AdoptedAlgorithm.can_redo().

Infinity.AdoptedAlgorithm.signals.can_undo_changed(adopted_algorithm, user, can_undo)
Signal Name:

can-undo-changed

Flags:

RUN_LAST

Parameters:

This signal is emitted every time the can-undo state of a local user in algorithm's user table changed. The can-undo state defines whether user can generate an undo request (via Infinity.AdoptedAlgorithm.generate_request()) in the current situation, see also Infinity.AdoptedAlgorithm.can_undo().

Infinity.AdoptedAlgorithm.signals.end_execute_request(adopted_algorithm, user, request, translated, error)
Signal Name:

end-execute-request

Flags:

RUN_LAST

Parameters:

This signal is emitted after a request has been executed. The request parameter is not necessarily the same as the one in the corresponding emission of Infinity.AdoptedAlgorithm ::begin-execute-request, however its effect on the buffer is the same. The difference is that the request in this signal might be reversible while the request in the Infinity.AdoptedAlgorithm ::begin-execute-request emission might not be reversible. The algorithm can make some requests reversible during their execution.

The translated request is the result of the transformation, i.e. it is always a Infinity.AdoptedRequestType.DO type request and its state vector corresponds to the current state. It has already been applied on the buffer by the algorithm. If request is of type Infinity.AdoptedRequestType.UNDO or Infinity.AdoptedRequestType.REDO then translated represents the operation that actually was performed on the buffer to undo or redo the effect of a previous request.

It can happen that an error occurs during execution. Usually this is due to invalid input, such as a request that cannot be transformed to the current state, a Infinity.AdoptedRequestType.UNDO request which has no corresponding Infinity.AdoptedRequestType.DO or Infinity.AdoptedRequestType.REDO request, or a request that ends up in an invalid operation (e.g. inserting text behind the end of the document). If such an error occurs then request is the same as the one in the Infinity.AdoptedAlgorithm ::begin-execute-request emission, translated may or may not be None and error contains information on the error occurred.

Property Details

Infinity.AdoptedAlgorithm.props.buffer
Name:

buffer

Type:

Infinity.Buffer

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The buffer to apply operations to

Infinity.AdoptedAlgorithm.props.buffer_modified_state
Name:

buffer-modified-state

Type:

Infinity.AdoptedStateVector

Default Value:

None

Flags:

READABLE

The state in which the buffer is considered not being modified

Infinity.AdoptedAlgorithm.props.current_state
Name:

current-state

Type:

Infinity.AdoptedStateVector

Default Value:

None

Flags:

READABLE

The state vector describing the current document state

Infinity.AdoptedAlgorithm.props.max_total_log_size
Name:

max-total-log-size

Type:

int

Default Value:

2048

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

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

Infinity.AdoptedAlgorithm.props.user_table
Name:

user-table

Type:

Infinity.UserTable

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The user table