D R A F T
Fluke: Flux -kernel Environment
Application Programming Interface Reference

Bryan Ford        Mike Hibler
The Flux Research Group
Department of Computer Science
University of Utah
Salt Lake City, UT, USA 84112
http://www.cs.utah.edu/projects/flux/
fluke@flux.cs.utah.edu

This specification documents Version 2 of the Fluke API. It is mostly complete and correct, with the exception of incomplete specification of the processor-specific aspects (section 12) and some evolving terminology. The API may evolve to a new version before the first formal release of the prototype kernel implementing the Fluke API.

A companion document, ``Fluke: Design Principles and Rationale,'' describes the Fluke execution architecture in detail. It will be available soon.

Copyright © 1996-1999, University of Utah. All rights reserved. The University of Utah grants you the right to copy and reproduce this document or portions thereof for academic, research, evaluation, and personal use only, provided that this title page appears prominently. To arrange for alternate terms, contact the University at csl-dist@cs.utah.edu or +1-801-585-3271.

• Contents
• 1 Introduction
  • 1.1 Object State
  • 1.2 Object Invocations
• 2 Thread
  • 2.1 Overview
  • 2.2 State
  • 2.3 References
  • 2.4 fluke_thread_create: create a new thread
  • 2.5 fluke_thread_create_hash: create a new thread with a given hash value
  • 2.6 fluke_thread_destroy: destroy a thread
  • 2.7 fluke_thread_disable_exceptions: prevent exceptions in the current thread
  • 2.8 fluke_thread_enable_exceptions: allow exceptions in the current thread
  • 2.9 fluke_thread_get_client: retrieve the ``client'' reliable-IPC link
  • 2.10 fluke_thread_get_handlers: return the exception handling routines registered for a thread.
  • 2.11 fluke_thread_get_saved_state: retrieve the exception state of a thread
  • 2.12 fluke_thread_get_server: retrieve the ``server'' reliable-IPC link
  • 2.13 fluke_thread_get_state: retrieve the current state of a thread
  • 2.14 fluke_thread_interrupt: interrupt another thread
  • 2.15 fluke_thread_move: move a thread object from one location to another
  • 2.16 fluke_thread_reference: associates a reference with a thread
  • 2.17 fluke_thread_return_from_exception: return from an exception handler
  • 2.18 fluke_thread_self: find the current thread
  • 2.19 fluke_thread_set_client: change the ``client'' reliable-IPC link
  • 2.20 fluke_thread_set_handlers: register the exception handling routines for a thread.
  • 2.21 fluke_thread_set_saved_state: restores exception state of a thread
  • 2.22 fluke_thread_set_server: change the ``server'' reliable-IPC link
  • 2.23 fluke_thread_set_state: set the current state of a thread object
  • 2.24 fluke_thread_schedule: schedule another thread to run
• 3 Task
  • 3.1 Overview
  • 3.2 State
  • 3.3 References
  • 3.4 fluke_task_create: create a new task
  • 3.5 fluke_task_create_hash: create a new task with a given hash value
  • 3.6 fluke_task_destroy: destroy a task
  • 3.7 fluke_task_get_state: retrieve the current state of a task object
  • 3.8 fluke_task_move: move a task object from one location to another
  • 3.9 fluke_task_reference: associates a reference with a task
  • 3.10 fluke_task_set_state: set the current state of a task object
• 4 Regions
  • 4.1 Overview
  • 4.2 State
  • 4.3 References
  • 4.4 fluke_region_create: create a new memory region
  • 4.5 fluke_region_create_hash: create a new memory region with a given hash value
  • 4.6 fluke_region_destroy: destroy a memory region
  • 4.7 fluke_region_get_state: retrieve the current state of a region object
  • 4.8 fluke_region_move: move a region object from one location to another
  • 4.9 fluke_region_protect: change the access permissions of a memory region
  • 4.10 fluke_region_reference: associates a reference with a memory region
  • 4.11 fluke_region_search: search for objects in a memory region
  • 4.12 fluke_region_set_state: set the current state of a region object
• 5 Mappings
  • 5.1 Overview
  • 5.2 State
  • 5.3 References
  • 5.4 fluke_mapping_create: create a new memory mapping
  • 5.5 fluke_mapping_create_hash: create a new memory mapping with a given hash value
  • 5.6 fluke_mapping_destroy: destroy a memory mapping
  • 5.7 fluke_mapping_get_state: retrieve the current state of a mapping object
  • 5.8 fluke_mapping_move: move a mapping object from one location to another
  • 5.9 fluke_mapping_protect: change the protection of an address mapping
  • 5.10 fluke_mapping_set_state: set the current state of a mapping object
• 6 Ports
  • 6.1 Overview
  • 6.2 State
  • 6.3 References
  • 6.4 fluke_port_create: create a new port
  • 6.5 fluke_port_create_hash: create a new port with a given hash value
  • 6.6 fluke_port_destroy: destroy a port
  • 6.7 fluke_port_get_state: retrieve the current state of a port
  • 6.8 fluke_port_move: move a port object from one location to another
  • 6.9 fluke_port_reference: associates a reference with a port
  • 6.10 fluke_port_set_state: set the current state of a port object
• 7 Port Sets
  • 7.1 Overview
  • 7.2 State
  • 7.3 References
  • 7.4 fluke_pset_create: create a new port set
  • 7.5 fluke_pset_create_hash: create a new port set with a given hash value
  • 7.6 fluke_pset_destroy: destroy a port set
  • 7.7 fluke_pset_get_state: retrieve the current state of a port set
  • 7.8 fluke_pset_move: move a port set object from one location to another
  • 7.9 fluke_pset_reference: associates a reference with a port set
  • 7.10 fluke_pset_set_state: set the current state of a port set
• 8 Interprocess Communication
  • 8.1 Overview
  • 8.2 IPC types
  • 8.3 IPC parameters
  • 8.4 fluke_ipc_call: make a synchronous idempotent call to a port
  • 8.5 fluke_ipc_client_connect_send: create a reliable connection to a server
  • 8.6 fluke_ipc_client_connect_send_over_receive: perform a reliable RPC to a server
  • 8.7 fluke_ipc_reply: reply to an idempotent call
  • 8.8 fluke_ipc_reply_wait_receive: reply to an idempotent call and wait for a new request
  • 8.9 fluke_ipc_send: send a one-way message to a port
  • 8.10 fluke_ipc_server_ack_send_wait_receive: reply to a reliable RPC and wait for another
  • 8.11 fluke_ipc_server_send_wait_receive: send data to a reliable IPC connection, disconnect and wait for a new invocation
  • 8.12 fluke_ipc_setup_wait_receive: set up a server thread and wait for incoming IPC invocations
  • 8.13 fluke_ipc_side_ack_send: become the sender on a reliable IPC connection
  • 8.14 fluke_ipc_side_ack_send_over_receive: reverse a reliable IPC connection, send a message and reverse again
  • 8.15 fluke_ipc_side_alert: send an interrupt on a reliable IPC connection
  • 8.16 fluke_ipc_side_disconnect: destroy a reliable IPC connection
  • 8.17 fluke_ipc_side_over_receive: reverse the transfer direction of a reliable IPC connection
  • 8.18 fluke_ipc_side_receive: receive data through reliable IPC
  • 8.19 fluke_ipc_side_send: send data across a reliable IPC connection
  • 8.20 fluke_ipc_side_send_over_receive: send a message on a reliable IPC connection and reverse the connection
  • 8.21 fluke_ipc_wait_receive: wait on a port set for incoming IPC invocations
• 9 Mutexes
  • 9.1 Overview
  • 9.2 State
  • 9.3 References
  • 9.4 fluke_mutex_create: create a new mutex
  • 9.5 fluke_mutex_create_hash: create a new mutex with a given hash value
  • 9.6 fluke_mutex_destroy: destroy a mutex
  • 9.7 fluke_mutex_get_state: retrieve the current state of a mutex
  • 9.8 fluke_mutex_lock: lock a mutex object
  • 9.9 fluke_mutex_move: move a mutex object from one location to another
  • 9.10 fluke_mutex_reference: associates a reference with a mutex
  • 9.11 fluke_mutex_set_state: set the current state of a mutex object
  • 9.12 fluke_mutex_trylock: attempt to lock a mutex object
  • 9.13 fluke_mutex_unlock: unlock a mutex object
• 10 Condition Variables
  • 10.1 Overview
  • 10.2 State
  • 10.3 References
  • 10.4 fluke_cond_broadcast: broadcast on a condition variable object
  • 10.5 fluke_cond_create: create a new condition variable
  • 10.6 fluke_cond_create_hash: create a new condition variable with a given hash value
  • 10.7 fluke_cond_destroy: destroy a condition variable
  • 10.8 fluke_cond_get_state: retrieve the current state of a condition variable
  • 10.9 fluke_cond_move: move a condition variable object from one location to another
  • 10.10 fluke_cond_reference: associates a reference with a condition variable
  • 10.11 fluke_cond_set_state: set the current state of a condition variable object
  • 10.12 fluke_cond_signal: signal on a condition variable object
  • 10.13 fluke_cond_wait: wait on a condition variable object
• 11 References
  • 11.1 Overview
  • 11.2 State
  • 11.3 References
  • 11.4 fluke_ref_check: determine if a reference is non-null
  • 11.5 fluke_ref_compare: determine if two references are equivalent
  • 11.6 fluke_ref_copy: make a copy of a reference object
  • 11.7 fluke_ref_create: create a new reference object
  • 11.8 fluke_ref_destroy: destroy a reference
  • 11.9 fluke_ref_hash: return the hash value of an object associated with a reference
  • 11.10 fluke_ref_move: move a reference object from one location to another
  • 11.11 fluke_ref_type: return the type of an object associated with a reference
• (X86) Processor-specific Fluke Interface
  • 12.1 Address Spaces
  • 12.2 System Calls
  • 12.3 Thread System Calls
  • 12.4 IPC System Calls
  • 12.5 Exception Handlers
• References
• About this document ...