|
Brazos C API: HOW TO Andréa M. Matsunaga & Maurício
O. Tsugawa |
Category |
API Member |
Return Value |
Description |
| Variables | MAX_USER_THREADS_PER_NODE | N/A |
Maximum number of user-spawned threads per DSM process. |
| NUM_LOCAL_USER_THREADS | N/A |
Number of user-spawned threads in calling process. | |
| TOTAL_USER_THREADS | N/A |
Total number of user-spawned threads in all processes over all machines. | |
Execution-related functions |
INITENV(int argc, char **argv, DWORD MemorySize) | None |
Initializes DSM environment. Should be called by all processes immediately after entering main(). <MemorySize> specifies the maximum amount of shared memory (in bytes) required by the user program’s execution. |
| CREATE_THREAD (HANDLE *Handle, DWORD ThreadStart) | BOOL – Returns TRUE if call was successful and FALSE if the call failed |
Called by a DSM process to spawn a new application thread. The handle for the new thread is returned in the <Handle> variable. The <ThreadStart> variable is the address of the function that the thread should begin executing upon creation. | |
| EXIT | None |
Must be called at the end of a program’s main() function to properly shut down the application. | |
| Shared-data allocation | G_MALLOC (char* ptr, DWORD size) | None |
Sets the value of <ptr> to a region of shared memory of <size> bytes. G_MALLOC should only be called by one application thread for each shared pointer, the value of which is then propagated to other DSM threads and processes automatically. |
| Synchronization calls | BARRIER | None |
Forces all threads (local and remote) to block at the call before any are allowed to proceed. |
| SCCLOCK(USHORT lock_id) | None |
Obtains a lock variable using the scope-consistency memory model. | |
| SCCUNLOCK(USHORT lock_id) | None |
Releases a lock variable previously obtained with a call to SCCLOCK. Variables modified within the critical section are passed to the next lock acquirer and no pages are invalidated. | |
| SccWriteInt(caddr_t addr, int val) | None |
Writes 4 bytes to the specified address within a scope-consistency critical section. | |
| SccWriteDouble(caddr_t addr, double val) | None |
Writes 8 bytes to the specified address within a scope-consistency critical section. | |
| RCLOCK(USHORT lock_id) | None |
Obtains a lock variable using the release consistent memory model. No consistency action taken when lock is obtained. | |
| RCUNLOCK(USHORT lock_id) | None |
Releases a lock variable obtained by a previous call to RCLOCK. All updates resulting from writes by the releasing process are flushed to all other processes before the release is allowed to complete. | |
| User Output | OUTPUT(TCHAR *format [ , arg...]) | None |
Sends formatted string to the Brazos User Interface that originally launched the DSM application. If the Brazos remote service is being used in debug mode, OUTPUT also prints to a process-specific output file (dsmprint0, dsmprint1, etc.). Semantics of call are the same as those of standard printf. |
| ERREXIT(TCHAR *format [, arg...]) | None |
Similar to OUTPUT call, but also forces a termination of currently running DSM application in all processes. | |
| getopt(int nargc, char *const *nargv, const char *ostr) | int |
Same as getopt in UNIX systems. | |
Thread ID calls |
GETMYLOCALID(DWORD *MyId) | None |
Called by a user-spawned thread to retrieve its thread id relative to other user-spawned threads in the same process. The ID is stored in <MyId>. |
| GETMYGLOBALID(DWORD *MyId) | None |
Called by a user-spawned thread to retrieve its thread id that is unique among all threads in all DSM processes. The ID is stored in <MyId>. | |
| Statistics | CLEAR_STATS | None |
Resets all Brazos stats to 0. |
| STATS_ON | None |
Starts statistics collection. | |
| STATS_OFF | None |
Ends statistics collection. | |
| START_CLOCK(LARGE_INTEGER *time) | None |
The variable <time> will contain the result of querying the hardware performance clock. | |
| END_CLOCK(LARGE_INTEGER StartTime, double time) | None |
The variable <time> will contain the time in seconds elapsed since the corresponding START_CLOCK call. <StartTime> is the parameter that was passed to the START_CLOCK function. |