InfAdoptedRequestLog: libinfinity-0.7 Reference Manual

## InfAdoptedRequestLog InfAdoptedRequestLog — History of requests |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfAdoptedRequestLog * | inf_adopted_request_log_new ()
guint | inf_adopted_request_log_get_user_id ()
guint | inf_adopted_request_log_get_begin ()
guint | inf_adopted_request_log_get_end ()
gboolean | inf_adopted_request_log_is_empty ()
void | inf_adopted_request_log_set_begin ()
InfAdoptedRequest * | inf_adopted_request_log_get_request ()
void | inf_adopted_request_log_add_request ()
void | inf_adopted_request_log_remove_requests ()
InfAdoptedRequest * | inf_adopted_request_log_next_associated ()
InfAdoptedRequest * | inf_adopted_request_log_prev_associated ()
InfAdoptedRequest * | inf_adopted_request_log_original_request ()
InfAdoptedRequest * | inf_adopted_request_log_next_undo ()
InfAdoptedRequest * | inf_adopted_request_log_next_redo ()
InfAdoptedRequest * | inf_adopted_request_log_upper_related ()
InfAdoptedRequest * | inf_adopted_request_log_lower_related ()
void | inf_adopted_request_log_add_cached_request ()
InfAdoptedRequest * | inf_adopted_request_log_lookup_cached_request ()

## Properties

guint | begin | Read / Write / Construct Only
guint | end | Read
InfAdoptedRequest * | next-redo | Read
InfAdoptedRequest * | next-undo | Read
guint | user-id | Read / Write / Construct Only

## Signals

void | add-request | Run Last

## Types and Values

struct | InfAdoptedRequestLog
struct | InfAdoptedRequestLogClass

## Object Hierarchy

        GObject
        ╰── InfAdoptedRequestLog

## Includes

    #include <libinfinity/adopted/inf-adopted-request-log.h>

## Description

InfAdoptedRequestLog stores all requests by a particular user. These need to be looked up by InfAdoptedAlgorithm to perform transformations of older requests to the current state. It also adds relations between the requests so that is easy to find the request that an Undo request undoes, or the Undo request undoing a given request, if available.

When requests are no longer needed, then they can also be removed again from the log, however requests can only be removed so that remaining Undo or Redo requests do not refer to some request that is about to be removed.

## Functions

### inf_adopted_request_log_new ()

    InfAdoptedRequestLog *
    inf_adopted_request_log_new (guint user_id);

Creates a new InfAdoptedRequestLog for the user with the given ID.

[constructor]

#### Parameters

user_id | The ID of the InfAdoptedUser to create a request log for. The request log only contains requests of that particular user. |

#### Returns

A new InfAdoptedRequestLog.

[transfer full]

### inf_adopted_request_log_get_user_id ()

    guint
    inf_adopted_request_log_get_user_id (InfAdoptedRequestLog *log);

Returns the ID of the user whose requests `log` contains.

#### Parameters

log | A InfAdoptedRequestLog. |

#### Returns

The log's user ID.

### inf_adopted_request_log_get_begin ()

    guint
    inf_adopted_request_log_get_begin (InfAdoptedRequestLog *log);

Returns the first index (i.e. the index of the oldest request) in the log.

#### Parameters

log | A InfAdoptedRequestLog. |

#### Returns

The first index in the log.

### inf_adopted_request_log_get_end ()

    guint
    inf_adopted_request_log_get_end (InfAdoptedRequestLog *log);

Returns the index a newly inserted request would have (i.e. one past the index of the newest request in the log). This ensures that `inf_adopted_request_log_get_end()` - `inf_adopted_request_log_get_begin()` reveals the number of requests in the log.

#### Parameters

log | A InfAdoptedRequestLog. |

#### Returns

The index of the next request in the log.

### inf_adopted_request_log_is_empty ()

    gboolean
    inf_adopted_request_log_is_empty (InfAdoptedRequestLog *log);

Returns whether `log` is empty. A log is empty if it does not contain any requsets.

#### Parameters

log | A InfAdoptedRequestLog. |

#### Returns

Whether `log` is empty.

### inf_adopted_request_log_set_begin ()

    void
    inf_adopted_request_log_set_begin (InfAdoptedRequestLog *log,
                                       guint n);

This function sets the index of the first log that will be added to `log` . For a new request log, this is set to 0. If you intend to insert a request sequence into `log` that does not start with 0, then you can call this function with the desired start index, so that `inf_adopted_request_log_get_begin()` and `inf_adopted_request_log_get_end()` return the correct value.

If you don't need `inf_adopted_request_log_get_begin()` or `inf_adopted_request_log_get_end()` before adding the first request to the log, then you don't need to call this function, since `inf_adopted_request_log_add_request()` will do it implicitely based on the request's vector time component for the request log's user.

This function can only be called if the request log is empty, see `inf_adopted_request_log_is_empty()`.

#### Parameters

log | A InfAdoptedRequestLog. |
n | The index of the first request to be added to the log. |

### inf_adopted_request_log_get_request ()

    InfAdoptedRequest *
    inf_adopted_request_log_get_request (InfAdoptedRequestLog *log,
                                         guint n);

Returns the request with the given index. Such a request must exist in `log` .

#### Parameters

log | A InfAdoptedRequestLog. |
n | The index of a request contained in `log` . |

#### Returns

A InfAdoptedRequest. The request is owned by the request log, you do not need to free it.

[transfer none]

### inf_adopted_request_log_add_request ()

    void
    inf_adopted_request_log_add_request (InfAdoptedRequestLog *log,
                                         InfAdoptedRequest *request);

Inserts `request` into `log` . The component represented by the log's user of the request's state vector must match the end index of `log` if `log` is not empty. Also, the user that issued `request` must be the same user as the one this request log belongs to.

#### Parameters

log | A InfAdoptedRequestLog. |
request | A InfAdoptedRequest. |

### inf_adopted_request_log_remove_requests ()

    void
    inf_adopted_request_log_remove_requests
                                   (InfAdoptedRequestLog *log,
                                    guint up_to);

Removes all requests with index lower than `up_to` . This function only works if the request before `up_to` is an "upper related" request. See `inf_adopted_request_log_upper_related()`. This condition guarantees that remaining requests do not refer to removed ones.

#### Parameters

log | A InfAdoptedRequestLog. |
up_to | The index of the first request not to remove. |

### inf_adopted_request_log_next_associated ()

    InfAdoptedRequest *
    inf_adopted_request_log_next_associated
                                   (InfAdoptedRequestLog *log,
                                    InfAdoptedRequest *request);

If `request` is of type `INF_ADOPTED_REQUEST_DO` or `INF_ADOPTED_REQUEST_REDO`, this returns UNDO request that undoes this request, if any. If `request` is a `INF_ADOPTED_REQUEST` UNDO request, this returns a request that redoes `request` , if any.

#### Parameters

log | A InfAdoptedRequestLog. |
request | A InfAdoptedRequest contained in `log` . |

#### Returns

The next associated request of `request` , or `NULL`.

[transfer none][allow-none]

### inf_adopted_request_log_prev_associated ()

    InfAdoptedRequest *
    inf_adopted_request_log_prev_associated
                                   (InfAdoptedRequestLog *log,
                                    InfAdoptedRequest *request);

If `request` is of type `INF_ADOPTED_REQUEST_REDO` or, this returns the UNDO request that is redone by `request` , if `request` is a `INF_ADOPTED_REQUEST_UNDO` request, this returns the request that is undone by `request` .

`request` must either be contained in `log` or the vector time component of its own user must be equivalent to `inf_adopted_request_log_get_end()`, in which case `request` is treated as it if was the newest request in `log` .

#### Parameters

log | A InfAdoptedRequestLog. |
request | A InfAdoptedRequest. |

#### Returns

The previous associated request of `request` , or `NULL`.

[transfer none][allow-none]

### inf_adopted_request_log_original_request ()

    InfAdoptedRequest *
    inf_adopted_request_log_original_request
                                   (InfAdoptedRequestLog *log,
                                    InfAdoptedRequest *request);

Returns the most previous associated request for `request` , that is, the `INF_ADOPTED_REQUEST_DO` request that `request` undoes or redoes, respectively. If `request` itself is a `INF_ADOPTED_REQUEST_DO` request, `request` itself is returned.

`request` must either be contained in `log` or the vector time component of its own user must be equivalent to `inf_adopted_request_log_get_end()`, in which case `request` is treated as it if was the newest request in `log` .

#### Parameters

log | A InfAdoptedRequestLog. |
request | A InfAdoptedRequest. |

#### Returns

The original request of `request` . This function never returns `NULL`.

[transfer none]

### inf_adopted_request_log_next_undo ()

    InfAdoptedRequest *
    inf_adopted_request_log_next_undo (InfAdoptedRequestLog *log);

Returns the request that would be undone if a undo request was added to the request log.

#### Parameters

log | A InfAdoptedRequestLog. |

#### Returns

The next request to be undone, or `NULL`.

[transfer none][allow-none]

### inf_adopted_request_log_next_redo ()

    InfAdoptedRequest *
    inf_adopted_request_log_next_redo (InfAdoptedRequestLog *log);

Returns the request that would be redone if a redo request was added to the request log.

#### Parameters

log | A InfAdoptedRequestLog. |

#### Returns

The next request to be redone, or `NULL`.

[transfer none][allow-none]

### inf_adopted_request_log_upper_related ()

    InfAdoptedRequest *
    inf_adopted_request_log_upper_related (InfAdoptedRequestLog *log,
                                           guint n);

Returns the newest request in `log` that is related to `n` th request in log. Requests are considered related when they are enclosed by a do/undo, an undo/redo or a redo/undo pair.

Note that the sets of related requests within a request log are disjoint.

#### Parameters

log | A InfAdoptedRequestLog. |
n | Index of a request in `log` . |

#### Returns

The newest request in `log` being related to the `n` th request.

[transfer none]

### inf_adopted_request_log_lower_related ()

    InfAdoptedRequest *
    inf_adopted_request_log_lower_related (InfAdoptedRequestLog *log,
                                           guint n);

Returns the oldest request in `log` that is related to `n` th request in log. Requests are considered related when they are enclosed by a do/undo, an undo/redo or a redo/undo pair.

Note that the sets of related requests within a request log are disjoint.

#### Parameters

log | A InfAdoptedRequestLog. |
n | Index of a request in `log` . |

#### Returns

The oldest request in `log` being related to the `n` th request.

[transfer none]

### inf_adopted_request_log_add_cached_request ()

    void
    inf_adopted_request_log_add_cached_request
                                   (InfAdoptedRequestLog *log,
                                    InfAdoptedRequest *request);

InfAdoptedRequestLog has a cache for translated requests built in. This can be used to store requests that have been translated to another point in the state space, and to efficiently look them up later. The advantage of having this functionality within InfAdoptedRequestLog is that when requests are removed from the log the cache is automatically updated accordingly.

The data structure of the cache is optimized for quick lookup of entries by the state vector and cleaning up entries in an efficient manner also when the cache has grown very big.

The request cache is mainly used by InfAdoptedAlgorithm to efficiently handle big transformations.

This function adds a request to the cache of the request log. `request` must be a translated version of a request existing in `log` .

#### Parameters

log | A InfAdoptedRequestLog. |
request | The InfAdoptedRequest to add to the cache. |

### inf_adopted_request_log_lookup_cached_request ()

    InfAdoptedRequest *
    inf_adopted_request_log_lookup_cached_request
                                   (InfAdoptedRequestLog *log,
                                    InfAdoptedStateVector *vec);

Looks up the request at `vec` from the cache of the request log. If the queried request does not exist in the cache, the function returns `NULL`.

See `inf_adopted_request_log_add_cached_request()` for an explanation of the request cache.

#### Parameters

log | A InfAdoptedRequestLog. |
vec | The state vector at which to look up the request. |

#### Returns

The cached InfAdoptedRequest according to `vec` , or `NULL`.

[transfer none][allow-none]

## Types and Values

### struct InfAdoptedRequestLog

    struct InfAdoptedRequestLog;

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

### struct InfAdoptedRequestLogClass

    struct InfAdoptedRequestLogClass {
      void(*add_request)(InfAdoptedRequestLog* log,
                         InfAdoptedRequest* request);
    };

This structure contains the default signal handlers for InfAdoptedRequestLog.

#### Members

`add_request` () | Default signal handler for the “add-request” signal. |

## Property Details

### The `“begin”` property

      “begin”                    guint

The first index contained in the log.

Owner: InfAdoptedRequestLog

Flags: Read / Write / Construct Only

Default value: 0

### The `“end”` property

      “end”                      guint

The index of the next request that is inserted into the log.

Owner: InfAdoptedRequestLog

Flags: Read

Default value: 0

### The `“next-redo”` property

      “next-redo”                InfAdoptedRequest *

The request that is redone when the user issues a redo request new.

Owner: InfAdoptedRequestLog

Flags: Read

### The `“next-undo”` property

      “next-undo”                InfAdoptedRequest *

The request that is undone when the user issues an undo request now.

Owner: InfAdoptedRequestLog

Flags: Read

### The `“user-id”` property

      “user-id”                  guint

The ID of the user whose requests the log contains.

Owner: InfAdoptedRequestLog

Flags: Read / Write / Construct Only

Default value: 0

## Signal Details

### The `“add-request”` signal

    void
    user_function (InfAdoptedRequestLog *log,
                   InfAdoptedRequest    *request,
                   gpointer              user_data)

This signal is emitted whenever a new request is added to the request log via `inf_adopted_request_log_add_request()`.

#### Parameters

log | The InfAdoptedRequestLog to which a new request is added. |
request | The new request being added. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

InfAdoptedRequest, InfAdoptedAlgorithm