Unify API

Global Variables and Macros
Initialization
General Segment Operations
Sequential-Access Segment Operations
Event Operations
Sequencer Operations
Command Line Parameters

Global Variables and Macros

This section describes global variables or macros that are available to Unify workers.

int Num_Workers

Num_Workers contains the number of Unify workers running at the current time.

int Worker_Id

Worker_Id is the identifier of the worker associated with the issuing process. Identifiers range from 1 to Num_Workers. The master is defined as worker number 1.

MASTER

MASTER is a macro that evaluates to 1 (also enum boolean True) if called by the master worker. For all other workers, MASTER evaluates to 0 (also enum boolean False).

START_EVENT_ID

START_EVENT_ID is a constant event identifier of type integer that refers to an initial event that is accessible by all workers after unify_startup() is called. This event may be used to synchronize initialization. The initial event count for START_EVENT_ID is 0.

USER_SEG_ID

USER_SEG_ID is a constant segment identifer of type integer that refers to a user segment that is accessible by all workers after unify_startup() is called. The user segment is provided to support application initialization. All workers are automatically placed in the copy set of the user segment.

Initialization

void unify_startup( int argc, char *argv[] )
int Create_Segment(type,shpr,prot,len,align)

type is one of RANDOM_SEGMENT, SEQUENTIAL_SEGMENT or ASSOCIATIVE_SEGMENT.

shpr is one of LOCAL_SEGMENT or SHARED_SEGMENT.

prot is any of R_ACCESS, W_ACCESS or X_ACCESS.

len is the requested length in bytes.

align is the required alignment for the segment

Create_Segment allocates a segment and returns a globally unique segment identifier. On return, the segment is allocated in the physical memory of the issuing process.

type=ASSOCIATIVE is not yet implemented.

The library currently does not use shpr or prot other than store that information.

Create_Segment returns the identifier of the allocated segment on success or -1 on failure.

char *Seg_Adr(int seg_id)

Seg_Adr returns a pointer to the segment specified by seg_id.
Seg_Adr returns NULL if seg_id refers to an invalid segment.

int Seg_Of_Adr(char *seg_adr)

Seg_Of_Adr returns the identifier of the segment that corresponds to the address given by seg_adr.
Seg_Of_Adr returns NULL if seg_adr does not correspond to any segment.

int Get_Updates(int seg_id)

Get_Updates retrieves the most recent copy of the segment specified by seg_id. On return, the worker is guaranteed to have the most recent copy of the segment in physical memory.

int Get_Updates_LL(int seg_id)

Get_Updates_LL retrieves the most recent copy of the segment specified by seg_id. On return, the worker is guaranteed to have the most recent copy of the segment in physical memory and will not relinquish updates to the segment until a subsequent Release_LL() (see below).

int Release_LL(int seg_id)

Release_LL allows the updates of a segment to be relinquished.
Release_LL returns 0 on success or -1 if the segment is invalid.

int Need_Updates(int seg_id)

Need_Updates adds the worker to the copy set of a segment specified by seg_id. On return, the worker is a member of the segment's copy set, and all other members of the copy know about the newly joined worker.

Need_Updates returns 0 on success or -1 if the segment is invalid.

int Dont_Need_Updates(int seg_id)

Dont_Need_Updates removes the worker from the copy set of a segment specified by seg_id. On return, the worker is no longer a member of the segment's copy set, and all other worker of the copy set know of the leaving worker.

int Put_Updates(int seg_id, enum send_type send_type)

Put_Updates distributes updates of the segment specified by seg_id to all processes in the segment's copy set. send_typeis an indication of whether the update has a Multicast or Concast behavior. On return, all members of the copy set are guaranteed to have the update.

Sequential-Access Segment Operations

int Seq_Write(int seg_id, char *buff,int len)

Seq_Write writes len bytes of the buffer pointed to by buff to the local copy of the sequential-access segment specified by seg_id. On return, the updates are reflected in the local segment copy of the issuing process.

int Seq_Read(int seg_id,char *buff,int len)

Seq_Read reads the next len bytes from the sequential-access segment specified by seg_id into the buffer specified by buff. This call will block if necessary until the next len bytes are available.

int Seq_Read_Nb(int seg_id,char *buff,int len)

Seq_Read_Nb attempts to read the next len bytes from the sequential-access segment specified by seg_id into the buffer specified by buff. This call will not block if len bytes are not immediately available.

int Get_Limit(int seg_id,unsigned *wrap,unsigned **writep)

Get_Limit returns the wrap count and write pointer (into *wrapand *writep, respectively) to the local copy of the sequential-access segment specified by seg_id.
Get_Limit returns 0 on success and -1 if the segment is invalid or not sequential-access.

int Seq_Wakeup(int seg_id,unsigned *wrap,unsigned *writep)

Seq_Wakeup blocks until the local copy of the sequential-access segment specified by seg_id has reched or surpassed the specified wrap count and write pointer, specified respectively by *wrap and *writep.

Event Operations

int Create_Event(void)

Create_Event allocates an event identifier to the issuing worker.
The count of an event is initialized to 0 upon creation of the event.

int Advance(int event_id)

Advance increments the count of the event specified by event_id. On return, the local count of the event reflects the increment, however, the advance notice may not yet be received by the other workers.

int Await(int event_id,unsigned count)

Await blocks the issusing worker until the local count of the event specified by event_id reaches or surpasses the value specified by count. On return, the local count of the event is equal to or greater than the specified count.

int Await_with_Timeout(int event_id,unsigned count,struct timeval *timeout)

Await_with_Timeout blocks the issuing worker until the local count of the event specifed by event_id reaches or surpasses the value specified by count. If the local count of the event has not reached or surpassed the specified count within the amount of time specified in timeout, the call returns with a notification of the timeout. (This function is not yet implemented).

int Event_Sync(int event_id)

Event_Sync brings the local count of the event specified by event_id into a consistent state. On return, the local count of the event reflects the number of advances on the event by all workers. (This function is not yet implemented).

int Event_Count(int event_id)

Event_Count returns the current local count of the event specified by event_id.
Event_Count returns -1 if the event identifier is invalid.

Sequencer Operations

int Create_Sequencer(void): Create_Sequencer allocates a globally unique sequencer identifier.; Create_Sequencer returns -1 on failure.

int Get_Ticket(int sequencer_id)

Get_Ticket returns the next number of the sequencer specified by sequencer_id.

The first ticket given for a particular sequencer is 0.

int Get_R_Ticket(int sequencer_id)

Get_R_Ticket returns an arbitrary unique number of the sequencer specified sequencer_id. (This function is not yet implemented).

Command Line Parameters

-c enable checkpointing

-d specifies debugging statements to be generated

-e specifies error messages to be generated

-f flushes messages as they are generated

-h this message

-v restart execution from a checkpoint

-m # maximum amount of memory to grab as the global address space.

-n # specifies the number of nodes in which to start

-t # initial frame timeout (in seconds)

-checkpoint enable checkpointing

-recover recover from a checkpoint

-noheartbeat disable heartbeat timeouts

Back to the Unify Home Page