GCS  0.2.3
Typedefs | Functions
gu_to.h File Reference
#include <stdint.h>
#include <stdbool.h>
#include <stdio.h>

Go to the source code of this file.

Typedefs

typedef int64_t gu_seqno_t
 
typedef struct gu_to gu_to_t
 

Functions

gu_to_tgu_to_create (int len, gu_seqno_t seqno)
 Creates TO object. TO object can be used to serialize access to application critical section using sequence number. More...
 
long gu_to_destroy (gu_to_t **to)
 Destroys TO object. More...
 
long gu_to_grab (gu_to_t *to, gu_seqno_t seqno)
 Grabs TO resource in the specified order. On successful return the mutex associated with specified TO is locked. Must be released gu_to_release(). More...
 
long gu_to_release (gu_to_t *to, gu_seqno_t seqno)
 Releases TO specified resource. On succesful return unlocks the mutex associated with TO. TO must be previously acquired with gu_to_grab(). More...
 
gu_seqno_t gu_to_seqno (gu_to_t *to)
 The last sequence number that had been used to access TO object. Note that since no locks are held, it is a conservative estimation. It is guaranteed however that returned seqno is no longer in use. More...
 
long gu_to_cancel (gu_to_t *to, gu_seqno_t seqno)
 cancels a TO monitor waiter making it return immediately It is assumed that the caller is currenly holding the TO. The to-be-cancelled waiter can be some later transaction but also some earlier transaction. Tests have shown that the latter case can also happen. More...
 
long gu_to_self_cancel (gu_to_t *to, gu_seqno_t seqno)
 
long gu_to_interrupt (gu_to_t *to, gu_seqno_t seqno)
 interrupts from TO monitor waiting state. Seqno remains valid in the queue and later seqnos still need to wait for this seqno to be released. More...
 

Detailed Description

Public TO monitor API

Typedef Documentation

typedef struct gu_to gu_to_t

Total Order object

Function Documentation

long gu_to_cancel ( gu_to_t to,
gu_seqno_t  seqno 
)

cancels a TO monitor waiter making it return immediately It is assumed that the caller is currenly holding the TO. The to-be-cancelled waiter can be some later transaction but also some earlier transaction. Tests have shown that the latter case can also happen.

Parameters
toA pointer to TO object.
seqnoSeqno of the waiter object to be cancelled
Returns
0 for success and -ERANGE, if trying to cancel an earlier transaction
gu_to_t* gu_to_create ( int  len,
gu_seqno_t  seqno 
)

Creates TO object. TO object can be used to serialize access to application critical section using sequence number.

Parameters
lenA length of the waiting queue. Should be no less than the possible maximum number of threads competing for the resource, but should not be too high either. Perhaps 1024 is good enough for most applications.
seqnoA starting sequence number (the first to be used by gu_to_grab()).
Returns
Pointer to TO object or NULL in case of error.
long gu_to_destroy ( gu_to_t **  to)

Destroys TO object.

Parameters
toA pointer to TO object to be destroyed
Returns
0 in case of success, negative code in case of error. In particular -EBUSY means the object is used by other threads.
long gu_to_grab ( gu_to_t to,
gu_seqno_t  seqno 
)

Grabs TO resource in the specified order. On successful return the mutex associated with specified TO is locked. Must be released gu_to_release().

See also
gu_to_release
Parameters
toTO resource to be acquired.
seqnoThe order at which TO resouce should be aquired. For any N gu_to_grab (to, N) will return exactly after gu_to_release (to, N-1).
Returns
0 in case of success, negative code in case of error. -EAGAIN means that there are too many threads waiting for TO already. It is safe to try again later. -ECANCEL if waiter was canceled, seqno is skipped in TO -EINTR if wait was interrupted, must retry grabbing later
long gu_to_interrupt ( gu_to_t to,
gu_seqno_t  seqno 
)

interrupts from TO monitor waiting state. Seqno remains valid in the queue and later seqnos still need to wait for this seqno to be released.

The caller can (and must) later try gu_to_grab() again or cancel the seqno with gu_to_self_cancel().

Parameters
toA pointer to TO object.
seqnoSeqno of the waiter object to be interrupted
Returns
0 for success and -ERANGE, if trying to interrupt an already used transaction
long gu_to_release ( gu_to_t to,
gu_seqno_t  seqno 
)

Releases TO specified resource. On succesful return unlocks the mutex associated with TO. TO must be previously acquired with gu_to_grab().

See also
gu_to_grab
Parameters
toTO resource that was previously acquired with gu_to_grab().
seqnoThe same number with which gu_to_grab() was called.
Returns
0 in case of success, negative code in case of error. Any error here is an application error - attempt to release TO resource out of order (not paired with gu_to_grab()).
long gu_to_self_cancel ( gu_to_t to,
gu_seqno_t  seqno 
)

Self cancel to without attempting to enter critical secion

gu_seqno_t gu_to_seqno ( gu_to_t to)

The last sequence number that had been used to access TO object. Note that since no locks are held, it is a conservative estimation. It is guaranteed however that returned seqno is no longer in use.

Parameters
toA pointer to TO object.
Returns
GCS sequence number. Since GCS TO sequence starts with 1, this sequence can start with 0.