My Project
Data Structures | Macros | Typedefs | Functions
symbol.h File Reference

Defines the interface to symbol.c functions (do not modify) More...

Go to the source code of this file.

Data Structures

struct  symbol
 

Macros

#define SYM_TAB_SIZE   997
 

Typedefs

typedef struct sym_table sym_table_t
 
typedef struct symbol symbol_t
 
typedef void(* iterate_fnc_t) (symbol_t *sym, void *data)
 

Functions

int symbol_add (sym_table_t *symTab, const char *name, int addr)
 
char * symbol_find_by_addr (sym_table_t *symTab, int addr)
 
symbol_tsymbol_find_by_name (sym_table_t *symTab, const char *name)
 
sym_table_tsymbol_init (int table_size)
 
void symbol_reset (sym_table_t *symTab)
 
struct nodesymbol_search (sym_table_t *symTab, const char *name, int *hash, int *index)
 
void symbol_term (sym_table_t *symTab)
 
void symbol_iterate (sym_table_t *symTab, iterate_fnc_t fnc, void *data)
 
void symbol_remove_by_addr (sym_table_t *symTab, int addr1, int addr2)
 

Detailed Description

This file defines the interface to a C file symbol.c that you will complete. The underlying data structure(s) used will be defined by the actual assignment. The assignment will define whether symbols are case sensitive or case in-sensitive.

In this implementation, you will learn about dynamic memory management using malloc/free. You will also learn about function pointers (callback functions).

Macro Definition Documentation

#define SYM_TAB_SIZE   997

Suggested size, 997 is a prime (primes reduce hashing collisions)

Typedef Documentation

typedef void(* iterate_fnc_t) (symbol_t *sym, void *data)

Defines the signature of a callback function (also known as a function pointer). This is how languages such as Java and C++ do dynamic binding (i.e. figure out which function to call). Recall that in Java the code obj.equals(object) will call one of possibly many different methods depending on the actual type of obj. This is because the method .equals() may be overridden.

In the LC3, dynamic binding is based on the JSRR opcode. With this opcode, the address of the routine to call is stored in a register and can be changed at runtime. Compare this to a JSR nameOfRoutine opcode which specifies what routine to call from the label that follows it. Thus, the address is fixed at assembly time.

This is used in the symbol_iterate() function. An interesting variation would be to have the callback function return an integer which determines whether the iteration should contibue or terminate.

Parameters
symTab- pointer to the symbol table
data- any additional information to be passed on to fnc. The called function will cast this to whatever type was actually passed.
typedef struct sym_table sym_table_t

This defines an opaque type. The actual contents of the structure are hidden in the implementation and only a pointer to this structure is used externally to this file. A pointer to an opaque structure is sometimes referred to as a handle.

typedef struct symbol symbol_t

The symbol_find methods return a pointer to this data structure. It is up to the implementor to decide how to use this stucture in the implementation.

Function Documentation

int symbol_add ( sym_table_t symTab,
const char *  name,
int  addr 
)

Add a symbol to the symbol table.

Parameters
symTab- pointer to the symbol table
name- the name of the symbol
addr- the address of the symbol
Returns
1 if neither the name or address are currently in the symbol table, 0 otherwise
Todo:
implement this function
char* symbol_find_by_addr ( sym_table_t symTab,
int  addr 
)

Find a name by its LC3 address

Parameters
symTab- pointer to the symbol table
addr- an LC3 address
Returns
the label at that address or NULL if no symbol is associated with the adddress.
Todo:
implement this function
symbol_t* symbol_find_by_name ( sym_table_t symTab,
const char *  name 
)

Find a symbol by its name

Parameters
symTab- pointer to the symbol table
name- the symbols name
Returns
the symbols information or NULL if no symbol is associated with the name. Most of the work is done by symbol_search(). That routine returns a node_t*, but this routine returns a symbol_t*. Study this posting to understand how you might solve this.
Todo:
implement this function
sym_table_t* symbol_init ( int  table_size)

Create a new symbol table and return a pointer to it. This function is a constructor for a symbol table. It allocates and initializes both the hash_table and the addr_table. The latter is an array of char* that is indexed by an LC3 address to find the label (if any) associated with that address.

Parameters
table_size- the size of the hash table.
Returns
a pointer to the symbol table.
Todo:
implement this function
void symbol_iterate ( sym_table_t symTab,
iterate_fnc_t  fnc,
void *  data 
)

This function calls the function for every entry in the symbol table. The assigment will define the order in which the entries should be visited.

Parameters
symTab- pointer to the symbol table
fnc- the function to be called on every element
data- any additional information to be passed on to fnc. The called function will cast this to whatever type was actually passed.
Todo:
implement this function
void symbol_remove_by_addr ( sym_table_t symTab,
int  addr1,
int  addr2 
)

Remove all entries from symbol table that have addresses in the given range.

Parameters
symTab- pointer to the symbol table
addr1- lowest address of range
addr2- highest address of range
Todo:
implement this function
void symbol_reset ( sym_table_t symTab)

Remove all the symbols from the symbol table. After this call the opaque symbol table pointer is still valid and new symbols may be added to it. If needed, clear the addr_table.

Parameters
symTab- pointer to the symbol table
Todo:
implement this function
struct node* symbol_search ( sym_table_t symTab,
const char *  name,
int *  hash,
int *  index 
)

This function is only used internally and should be declared static. It is a useful support function for the add()/find() functions. It is declared here for documentation purposes.

Parameters
symTab- pointer to the symbol table
name- the name of the symbol
hash- pointer to location where hash value will be stored
index- pointer to location where index will be stored
Returns
the nodes information or NULL if no symbol is associated with the name.
Todo:
implement this function
void symbol_term ( sym_table_t symTab)

Remove all symbols from the symbol table, and free all allocated memory. This function is a destructor for a symbol table. There must not be any memory leaks. After executing this function, the opaque pointer to the symbol table is no longer valid.

Todo:
implement this function