|
|
#ifndef _TICKET_HPP_
#define _TICKET_HPP_
// Ruler
// 1 2 3 4 5 6 7 8
//345678901234567890123456789012345678901234567890123456789012345678901234567890
/********************************************************************/ /* */ /* The standard layout. */ /* */ /* The standard layout for 'hpp' files for this code is as */ /* follows: */ /* */ /* 1. Include files. */ /* 2. Constants exported from the class. */ /* 3. Data structures exported from the class. */ /* 4. Forward references to other data structures. */ /* 5. Class specifications (including inline functions). */ /* 6. Additional large inline functions. */ /* */ /* Any portion that is not required is simply omitted. */ /* */ /********************************************************************/
#include "Global.hpp"
#include "Lock.hpp"
#include "Vector.hpp"
/********************************************************************/ /* */ /* Constants exported from the class. */ /* */ /* The ticket constants specify the initial size of the */ /* ticket array. */ /* */ /********************************************************************/
CONST SBIT32 TicketSize = 128;
/********************************************************************/ /* */ /* Ticketing to maintain ordering. */ /* */ /* This class provides general purpose event ordering so */ /* that events can arrive in any order but processed in */ /* sequential order with a minimal amount of fuss. */ /* */ /********************************************************************/
template <class TYPE,class LOCK=NO_LOCK> class TICKET : public LOCK { //
// Private data structure.
//
typedef struct { BOOLEAN Available; TYPE Data; } STUB;
//
// Private data.
//
SBIT32 MaxSize;
SBIT32 Back; SBIT32 Front;
SBIT32 Base; SBIT32 Stride;
VECTOR<STUB> Ticket;
public: //
// Public functions.
//
TICKET ( SBIT32 Start = 0, SBIT32 NewMaxSize = TicketSize, SBIT32 NewStride = 1 );
BOOLEAN CollectTicket( TYPE *Data,SBIT32 *Ticket );
SBIT32 NumberOfTickets( VOID );
SBIT32 NewTicket( VOID );
BOOLEAN PunchTicket( CONST TYPE & Data,SBIT32 Ticket );
~TICKET( VOID );
//
// Public inline functions.
//
SBIT32 LowestOutstandingTicket( VOID ) { return Base; }
private:
//
// Disabled operations.
//
TICKET( CONST TICKET & Copy );
VOID operator=( CONST TICKET & Copy ); };
/********************************************************************/ /* */ /* Class constructor. */ /* */ /* Create a new ticket queue and prepare it for use. This call */ /* is not thread safe and should only be made in a single thread */ /* environment. */ /* */ /********************************************************************/
template <class TYPE,class LOCK> TICKET<TYPE,LOCK>::TICKET ( SBIT32 Start, SBIT32 NewMaxSize, SBIT32 NewStride ) : //
// Call the constructors for the contained classes.
//
Queue( NewMaxSize,1,CacheLineSize ) {#ifdef DEBUGGING
if ( NewMaxSize > 0 ) {#endif
//
// Setup the control information.
//
MaxSize = NewMaxSize;
//
// Setup the queue so it is empty.
//
Back = 0; Front = 0;
//
// Set the initial ticket number.
//
Base = Start; Stride = NewStride;#ifdef DEBUGGING
} else { Failure( "MaxSize in constructor for TICKET" ); }#endif
}
/********************************************************************/ /* */ /* Issue a new ticket. */ /* */ /* We issue a new ticket and allocate a place in the line. We */ /* also we reserve space in the ticket queue. */ /* */ /********************************************************************/
template <class TYPE,class LOCK> SBIT32 TICKET<TYPE,LOCK>::NewTicket( VOID ) { REGISTER SBIT32 Result;
//
// Claim an exclisive lock (if enabled).
//
ClaimExclusiveLock();
//
// Add element to the queue. If necessary wrap round
// to the front of the array.
//
Ticket[ Back ++ ].Available = False;
if ( Back >= MaxSize ) { Back = 0; }
//
// Compute the ticket number.
//
Result = (Base + (NumberOfTickets() * Stride));
//
// Verify that the queue is not full. If it is full then
// double its size and copy wrapped data to the correct
// position in the new array.
//
if ( Front == Back ) { REGISTER SBIT32 Count; REGISTER SBIT32 NewSize = (MaxSize * ExpandStore);
//
// Expand the queue (it will be at least doubled).
//
Ticket.Resize( NewSize );
//
// Copy the tail end of the queue to the correct
// place in the expanded queue.
//
for ( Count = 0;Count < Back;Count ++ ) { Ticket[ (MaxSize + Count) ] = Ticket[ Count ]; }
//
// Update the control information.
//
Back += MaxSize; MaxSize = NewSize; }
//
// Release any lock we claimed earlier.
//
ReleaseExclusiveLock();
return Result; }
/********************************************************************/ /* */ /* Punch a ticket and store any associated data. */ /* */ /* We punch a ticket so it can be collected and store any */ /* related data. */ /* */ /********************************************************************/
template <class TYPE,class LOCK> BOOLEAN TICKET<TYPE,LOCK>::PunchTicket ( CONST TYPE & Data, SBIT32 Ticket ) { REGISTER BOOLEAN Result; REGISTER SBIT32 TicketOffset;
//
// Claim an exclusive lock (if enabled).
//
ClaimExclusiveLock();
//
// Compute the offset in the ticket array.
//
TicketOffset = ((Ticket - Base) / Stride);
//
// Ensure the ticket refers to and active ticket
// that has not already been recycled.
//
if ( (TicketOffset >= 0) && (TicketOffset < NumberOfTickets()) ) { REGISTER STUB *Stub = & Ticket[ TicketOffset ];
//
// Ensure the ticket has not already been
// punched.
//
if ( ! Stub -> Available ) { Stub -> Available = True; Stub -> Data = Data;
Result = True; } else { Result = False; } } else { Result = False; }
//
// Release any lock we claimed earlier.
//
ReleaseExclusiveLock();
return Result; }
/********************************************************************/ /* */ /* Collect the lowest numbered ticket. */ /* */ /* We try to collect the lowest numbered ticket that has been */ /* issued. If it is has been punched and is available we */ /* recycle it after returning any associated data to the caller. */ /* */ /********************************************************************/
template <class TYPE,class LOCK> BOOLEAN TICKET<TYPE,LOCK>::CollectTicket ( TYPE *Data, SBIT32 *Ticket ) { REGISTER BOOLEAN Result;
//
// Claim an exclusive lock (if enabled).
//
ClaimExclusiveLock();
//
// We make sure the ticket queue is not empty.
//
if ( Front != Back ) { REGISTER STUB *Stub = & Ticket[ Front ];
//
// We can collect the first ticket in the
// ticket queue if it has been punched.
//
if ( Stub -> Available ) { //
// We have an ticket ready so return it to
// the caller. If we walk off the end of
// the ticket queue then wrap to the other
// end.
//
(*Data) = Stub -> Data; (*Ticket) = (Base += Stride);
if ( (++ Front) >= MaxSize ) { Front = 0; }
Result = True; } else { Result = False; } } else { Result = False; }
//
// Release any lock we claimed earlier.
//
ReleaseExclusiveLock();
return Result; }
/********************************************************************/ /* */ /* Calculate the size of the reorder queue. */ /* */ /* Calculate the size of the queue and return it to the caller. */ /* */ /********************************************************************/
template <class TYPE,class LOCK> SBIT32 TICKET<TYPE,LOCK>::NumberOfTickets( VOID ) { REGISTER SBIT32 Size;
//
// Compute the size of the reorder queue.
//
Size = (Back - Front);
//
// If the queue has wrapped then adjust as needed.
//
if ( Size < 0 ) { Size += MaxSize; }
return Size; }
/********************************************************************/ /* */ /* Class destructor. */ /* */ /* Destory a queue. This call is not thread safe and should */ /* only be made in a single thread environment. */ /* */ /********************************************************************/
template <class TYPE,class LOCK> TICKET<TYPE,LOCK>::~TICKET( VOID ) { /* void */ }#endif
|
