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)
 

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
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 the symbol is not currently in the symbol table, 0 if the symbol already exists. If appropriate, add the name to the addr_table. The firstsymbol with a given address should be stored in the addr_table.
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 address.
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.
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. This function should also allocate and initialize an address table with LC3_MEMORY_SIZE (65536) entries.

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_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. Also 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