Please note that these Trac pages are no longer being updated. Wiki contents/documentation have moved to GitHub.

Version 58 (modified by justinc, 10 years ago)

--

Future Repy Library Reference



For a detailed description of Network API call semantics see: [NetworkApiSemantics]. (Read the description of calls on this page first.)

I have made the following resource consumption simplifications to make the interface easier to understand:

  • I assume that the minimum packet size is 64 bytes and all data consumes extra space. This unfairly penalizes small packets.
  • I assume there is no maximum packet size. This slightly benefits large packets / messages / sends.
  • I assume that every separate network API call will result in a separate packet. This presumes no 'batching' occurs.
  • I assume that every disk I/O operation touches a separate block.
  • I assume that a disk block has size 4K.
  • I assume that every chunk of file data is aligned on 4K intervals. This means that small reads / writes may cross blocks if they are done at 4K boundaries.
  • I assume that each file that is created results in 4K of space and disk I/O.

For more information on the Exception hierarchy for Repy 2.0, see FutureRepyExceptionHierarchy?.


Introduction and Purpose


This document describes the narrow API available to repy programs. This document includes all of the calls that are available to a repy program and the use and meaning of these calls. For items built into the python programming language (like list operations, etc.) see the appropriate Python documentation.

The intent is that we will build libraries that will provide 'rich' functionality on top of these abstractions. For example, the file-like objects don't support next, but we can build this in a library. Also, notice that the logging mechanism doesn't support multiple arguments / do type conversion. We can do this in a user level library. We will expect that all users will load this library (and may even do it for them).


Cheat Sheet


Variable NameShort descriptionTutorial Section
callargscallargs are the command line arguments for your program (similar to Python's sys.argv[1:])example 2.2
callfunccallfunc is a string that indicates if the program was called for initialization or exit.example 1.1
mycontextmycontext is a shared dictionary that is used in place of global variables.example 1.3

Justin: Do callfunc and mycontext go away? Are they implemented in a system library?


Object NameShort descriptionTutorial Section
filesimilar to Python's file objectexample 2.1
socketsimilar to Python's socket objectexample 1.2
locksimilar to Python's threading.Lock objectexample 1.6
tcpserversocketA way to obtain incoming connectionsnew
udpserversocketA way to obtain incoming packetsnew
virtualnamespaceA way to evaluate statically analyzed codenew


Object / Function NameShort descriptionTutorial Section
file.readatRead data from a file (maybe seek first).N/A (new call)
file.writeatWrite data to a file (maybe seek first).N/A (new call)
file.closeClose an open file.example 2.1
socket.recvRead data from a socketexample 1.2
socket.sendSend data on a socketexample 1.2
socket.closeCloses a socketexample 3.2
socket.willblockReturns an indicator of whether or not a socket will block N/A (new call)
lock.acquireAcquire the lockexample 1.6
lock.releaseRelease the lockexample 1.6
tcpserversocket.getconnectionReturns a socket from a new connection N/A (new call)
tcpserversocket.closeStops listening for connections new call
udpserversocket.getmessageReturns a UDP packet N/A (new call)
udpserversocket.closeStops listening for connections new call
virtualnamespace.evaluateEvaluates the code in a given global contextnew call


Function NameShort descriptionTutorial Section
openfileopens file objects. example 2.1
listfilesReturns a list of file names for the files in the vesselexample 2.2
removefilesimilar to Python's os.remove() functionexample 2.2
sleepsimilar to Python's time.sleep() functionexample 1.6
randombytessimilar to Python's os.urandom() function(new call) example 4.2
createlocksimilar to Python's threading.Lock() constructorexample 1.6
exitallsimilar to Python's sys.exit() or os._exit()example 3.2
getruntimegets the time since the program was startedexample 1.4
gethostbyname_exsimilar to Python's socket.gethostbyname_ex() functionexample 4.1
getmyipgets an external IP address of the computerexample 4.1
sendmessagesends a message to another computerexample 4.2
openconnectionopens a connection to another computer (blocking)example 3.1
listenforconnectionreturn a tcpserversocket that can be used to accept incoming connectionsnew
listenformessagereturn a udpserversocket that can be used to accept incoming messagesnew
createthreadcreates a new thread to execute a function with a set of argumentsnew (example 1.4)
circularloglogs information to the circular logging buffer (replaces print)example 1.1
getthreadnameprovides a unique string that indicates the name of the current threadNew call
createvirtualnamespaceProvides a virtualnamespace object that can be used to evaluate codeNew call
getresourcesProvides two dictionaries which represent the resource limits and usageNew call


Detailed description



Shared variables



mycontext


Mycontext is a dictionary that is shared between all of the threads in your program. The intent is that mycontext will be used in the place of global variables. See the tutorial for examples using mycontext.


callfunc


Your program may choose to have different functionality that executes at different times. The callfunc variable is set to values that indicate what the state of execution is. Callfunc is set to either "initialize" and "exit". These are executed by running the program as a script and setting the variable callfunc to either the string "initialize" or the string "exit". The "initialize" is the first time that your program executes. If initialize finishes and there are no pending threads or callbacks, the program is called with "exit" to allow it a chance to clean up.

Justin C.: Should we remove this? We could register a function to be called at exit only using a library above.


callargs


Callargs is a list of strings that contain the arguments your program was called with. If there are no arguments, callargs contains an empty list.


API functions



gethostbyname_ex(name)


(from the Python documentation) Translate a host name to IPv4 address format, extended interface. Return a triple (hostname, aliaslist, ipaddrlist) where hostname is the primary host name responding to the given ip_address, aliaslist is a (possibly empty) list of alternative host names for the same address, and ipaddrlist is a list of IPv4 addresses for the same interface on the same host (often but not always a single address). gethostbyname_ex() does not support IPv6 name resolution, and getaddrinfo() should be used instead for IPv4/v6 dual stack support.

  • Doc string:

<Purpose>

Provides information about a hostname. Calls socket.gethostbyname_ex()

<Arguments>

name:

The host name to get information about

<Exceptions>

NetworkAddressError? (descends from NetworkError?) if the address cannot be resolved

<Side Effects>

None.

<Resource Consumption>

This operation consumes network bandwidth of 4K netrecv, 1K netsend. (It's hard to tell how much was actually sent / received at this level)

<Returns>

A tuple containing (hostname, aliaslist, ipaddrlist). See the python docs for socket.gethostbyname_ex()


getmyip()


Returns the localhost's "Internet facing" IP address. It may raise an exception on hosts that are not connected to the Internet.

Justin: What if there are multiple interfaces? Should this return a list?

  • Doc string:

<Purpose>

Provides the external IP of this computer. Does some clever trickery.

<Arguments>

None

<Exceptions>

InternetConnectivityError? (descends NetworkError?) if the host is not connected to the Internet or has name resolution problems

<Side Effects>

None.

<Resource Consumption>

This operation consumes 64*4 bytes of netsend (SYN, ACK, FIN/ACK, Last-ACK) and 64*2 bytes of netrecv (SYN/ACK, FIN / ACK)

<Returns>

The localhost's IP address


sendmessage(desthost, destport, message, localip, localport)


(rename of sendmess)

Sends a UDP message to a destination host / port using a specified localip and localport. Returns the number of bytes sent.

  • Doc string:

<Purpose>

Send a message to a host / port

<Arguments>

desthost:

The host to send a message to

destport:

The port to send the message to

message:

The message to send

localhost:

The local IP to send the message from

localport:

The local port to send the message from

<Exceptions>

AddressBindingError? (descends NetworkError?) when the local IP isn't a local IP

PortRestrictedException? (descends ResourceException?) when the local port isn't allowed

TypeError/ValueError? when the local IP and port aren't valid types or values

<Side Effects>

None.

<Resource Consumption>

This operation consumes 64 bytes + number of bytes of the message that were transmitted. This requires that the localport is allowed.

<Returns>

The number of bytes sent on success


listenformessage(localip, localport)


Binds to a IP and port and waits for incoming UDP messages. If this function is called multiple times on the same ip and port without the first udpserversocket being closed, the second call with have an exception. These ports are separate from the connection ports and so both a message and connection listener can use the same port.

* Doc string:

<Purpose>

Sets up a udpserversocket to receive incoming UDP messages

<Arguments>

localip:

The local IP or hostname to register the handler on

localport:

The port to listen on

<Exceptions>

PortInUseException? (descends NetworkError?) if the port cannot be listened on because some other process on the system is listening on it

PortInUseException? if there is already a udpserversocket with the same IP and port.

TypeError/ValueError? if the port number or ip is wrong type or obviously invalid.

AddressBindingError? (descends NetworkError?) if the IP address isn't a local IP.

PortRestrictedException? (descends ResourceException?) if the port is restricted

<Side Effects>

Prevents other udpserversockets from using this port / IP

<Resource Consumption>

This operation consumes an insocket and requires that the provided messport is allowed.

<Returns>

The udpserversocket.


openconnection(desthost, destport, localip, localport, timeout)


(rename of openconn)

Open a TCP connection to a remote computer, returning a socket object. There is a timeout value that can be set to limit the amount of time the system will wait for a response before abandoning the attempt to connect.

  • Doc string:

<Purpose>

Opens a connection, returning a socket-like object

<Arguments>

desthost:

The host to open communications with

destport:

The port to use for communication

localip:

The local ip to use for the communication

localport:

The local port to use for communication

timeout:

The maximum amount of time to wait to connect

<Exceptions>

AddressBindingError? (descends NetworkError?) if the localip isn't associated with the local system

PortInUseException? (descends NetworkError?) if the localport is already used

PortRestrictedException? (descends ResourceException?) if the localport isn't allowed

ValueError? if the connection cannot be established due to a bad destination IP address

ConnectionRefusedException? (descends NetworkError?) if the connection cannot be established because the destination port isn't being listened on

TimeoutException? (common to all API functions that timeout) if the connection times out

ValueError/TypeError? if the arguments are invalid

Justin: What happens if the timeout is huge? Does this have any implications for the tcpserversocket?

<Side Effects>

None.

<Resource Consumption>

This operation consumes 64*2 bytes of netsend (SYN, ACK) and 64 bytes of netrecv (SYN/ACK). This requires that the localport is allowed. Upon success, this call consumes an outsocket.

<Returns>

A socket-like object that can be used for communication. Use send, recv, and close just like you would an actual socket object in python.


listenforconnection(localip, localport)


Binds to a IP and port and waits for incoming TCP connections. If this function is called multiple times on the same ip and port without the first tcpserversocket being closed, the second call with have an exception. These ports are separate from the message ports and so both a message and connection listener can use the same port.

* Doc string:

<Purpose>

Sets up a tcpserversocket to receive incoming TCP connections

<Arguments>

localip:

The local IP or hostname to register the handler on

localport:

The port to listen on

<Exceptions>

PortInUseException? (descends NetworkError?) if another process has already bound the ip/port

PortInUseException? if there is already a tcpserversocket with the same IP and port.

TypeError/ValueError? if the IP or port number is invalid.

PortRestrictedException? (descends ResourceException?) if the port number isn't allowed

AddressBindingError? (descends NetworkError?) if the IP address isn't a local IP.

<Side Effects>

The IP / port combination cannot be reused by a tcpserversocket until closed.

<Resource Consumption>

This call consumes an insocket and requires that the localport is allowed.

<Returns>

The tcpserversocket.


openfile(filename, create)


(Replaces: open, file.)

Open a file, returning an object of the file type.

Filenames may only be in the current directory and contain lowercase letters, numbers, the hyphen, underscore, and period character and may not be '.' or '..'. There is no concept of a directory or a folder in repy. Filenames must be no more than 30 characters long.

Every file object is capable of both reading and writing.

If create is True, the file is created if it does not exist. Neither mode truncates the file on open.

  • Doc string:

<Purpose>

Allows the user program to open a file safely. This function is not meant to resemble the builtin "open".

<Arguments>

filename:

The file that should be operated on

create:

If True, create the file if it doesn't exist already.

<Exceptions>

TypeError/ValueError? if one of the arguments is invalid (this includes e.g. the length being longer than 255 characters)

FileNotFoundError? if the file does not exist and create is false.

XXXException if the file is already opened. (This is handled at the system library level)

An internal error will cause the program to terminate if the file has incorrect permissions or similar errors occur.

<Side Effects>

Opens a file on disk, using a file descriptor.

<Resource Consumption>

This consumes 4K of fileread. If this is the first call on this file, this consumes a filesopened resource. If the file is created, this consumes 4K of filewrite.

<Returns>

A file-like object.


file.close()


Close the file. A closed file cannot be read or written any more. Any operation which requires that the file be open will raise a ValueError XXXException after the file has been closed. Calling close() more than once is allowed.

Conrad: Python raises ValueError in such situations. Any reason we think this should change? Also: I think (for consistency) we should raise ValueError if they try to call any method on a closed file -- close() included.

  • Doc string:

<Purpose>

Allows the user program to close a file. This function is meant to resemble the builtin "file.close".

<Arguments>

None.

<Exceptions>

None.

<Side Effects>

Closes a file descriptor previously opened for writing.

<Resource Consumption>

If this is the last opened file-like object on this file, this stops consuming a filesopened resource.

<Returns>

Nothing.


file.readat(sizelimit, offset)


Seek to a location in a file and reads up to sizelimit bytes from the file, returning what is read. If sizelimit is None, the file is read to EOF.

  • Doc string:

<Purpose>

Reads from a file handle. Reading 0 bytes informs you if you have read past the end-of-file, but returns no data.

<Arguments>

sizelimit - Specify a maximum number of bytes to read from the

file. Hitting EOF will read less.

offset - Seek to a specific location in the file before

reading.

<Exceptions>

ValueError? if the file is closed.

TypeError? if offset or sizelimit is not a non-zero integer.

XXXException if trying to read past the end of the file

<Side Effects>

Reads data from persistent storage. All write calls that occurred before this operation will be reflected in the data that is read.

<Resource Consumption>

Consumes 4K of fileread for each 4K aligned-block of the file read. All reads will consume at least 4K.

<Returns>

The data that was read; this may be the empty string if we have reached the end of the file. The only other case where the returned data is empty is when the sizelimit was zero and the offset was within the file.


file.writeat(data, offset)


Seek to the offset in the file and then write some data to a file.

  • Doc string:

<Purpose>

Allows the user program to write data to a file (and optionally seek somewhere first).

<Arguments>

Data to write (a string).

Offset (optional) - where to seek in the file first.

<Exceptions>

ValueError? if the file is closed.

An interal error terminates the program if the disk is out of space or some low level IO error occurs.

TypeError? if offset isn't an non-negative integer or data isn't a string.

XXXException if the offset is past the end of the file.

<Side Effects>

Writes data to persistent storage.

<Resource Consumption>

Consumes 4K of filewrite for each 4K aligned-block of the file written. All writes consume at least 4K.

<Returns>

Nothing.


listfiles()


Returns a list of file names for the files in the vessel.

  • Doc string:

<Purpose>

Returns a list of files accessible to the program.

<Arguments>

None

<Exceptions>

None

<Side Effects>

None

<Resource Consumption>

Consumes 4K of fileread.

<Returns>

A list of strings (file names)


removefile(filename)


Deletes a file in the vessel. If the file does not exist, an exception is raised.

  • Doc string:

<Purpose>

Allows the user program to remove a file in their area.

<Arguments>

filename: the name of the file to remove. It must not contain characters other than 'a-zA-Z0-9.-_' and cannot be '.' or '..'

<Exceptions>

FileNotFoundError? is raised if the file does not exist

TypeError/ValueError? if the filename param isn't the right type or is an invalid filename

Justin: ??? What if the file is open???

<Side Effects>

None

<Resource Consumption>

Consumes 4K of fileread. If successful, consumes 4K of filewrite.

<Returns>

None


exitall()


Terminates the program immediately. The program will not execute the "exit" callfunc or finally blocks.

  • Doc string:

<Purpose>

Allows the user program to stop execution of the program without passing an exit to the main program or calling finally blocks.

<Arguments>

None.

<Exceptions>

None.

<Side Effects>

There isn't a guaranteed time which this function is realized. This means that other threads may execute while this call is being processed.

<Resource Consumption>

None.

<Returns>

The current thread does not resume after exit


createlock()


Returns a lock object that can be used for mutual exclusion and critical section protection.

  • Doc string:

<Purpose>

Returns a lock object to the user program. A lock object supports two functions: acquire and release. See threading.Lock() for details

<Arguments>

None.

<Exceptions>

None.

<Side Effects>

None.

<Resource Consumption>

None.

<Returns>

The lock object.


lock.acquire(blocking=1)


Blocks until the lock is available, then takes it (lock is an object obtained by calling createlock()).

If the optional "blocking" argument is False, the method returns False immediately instead of waiting to acquire the lock; if the lock is available it takes it and returns True, as if it were called with no argument.

  • Doc string:

<Purpose>

Acquires a lock.

<Arguments>

blocking (optional) - if False, returns immediately instead of waiting to acquire the lock.

<Exceptions>

None.

<Side Effects>

Locks the object.

<Resource Consumption>

None.

<Returns>

True if the lock was acquired, False otherwise.


lock.release()


Releases the lock. This call raises an exception (?) if the lock is already unlocked.

  • Doc string:

<Purpose>

Release a lock.

<Arguments>

None.

<Exceptions>

XXXException if release() is called on an unlocked lock. Conrad: Do we want to raise an exception in this case?

<Side Effects>

Unlocks the object.

<Resource Consumption>

None.

<Returns>

None.


getruntime()


Returns a float containing the number of seconds the program has been running. This time is guaranteed to be monotonic.

  • Doc string:

<Purpose>

Return the amount of time the program has been running. This is in wall clock time.

<Arguments>

None

<Exceptions>

None.

<Side Effects>

None

<Resource Consumption>

None.

<Returns>

The elapsed time as float


randombytes()


Returns a string of random bytes of data derived from a hardware source of randomness. The size of the string will be equal to 1024. It is assumed that a client library that regularly needs small amounts of random data will cache data received from this call and return smaller values.

  • Doc string:

<Purpose>

Return a string of random bytes with length 1024

<Arguments>

None.

<Exceptions>

None.

<Side Effects>

This function is metered because it may involve using a hardware source of randomness.

<Resource Consumption>

This operation consumes 1024 bytes of random data.

<Returns>

The string of bytes.


createthread(function, args)


Start a new thread to call a function with a set of arguments. The thread is charged to your program.

  • Doc string:

<Purpose>

Cause the execution of a function in another thread. The current thread of execution will also proceed.

<Arguments>

function:

The function to call

args:

The arguments to pass to the function. This can be a tuple or a list

<Exceptions>

TypeError if the function parameter isn't callable.

<Side Effects>

None.

<Resource Consumption>

This operation consumes a thread.

<Returns>

None


sleep(seconds)


Sleeps the current thread for some time (waits for a specific time before executing any further instructions). This thread will not consume CPU cycles during this time.

  • Doc string:

<Purpose>

Allow the current thread to pause execution (similar to time.sleep()). This function will not return early for any reason

<Arguments>

seconds:

The number of seconds to sleep. This can be a floating point value

<Exceptions>

None.

<Side Effects>

None.

<Resource Consumption>

None.

<Returns>

None.


socket.close()


Closes the socket. Any further local calls to recv / send will result in an exception.

  • Doc string:

<Purpose>

Closes a socket. Pending remote recv() calls will return with the remaining information. Local recv / send calls will fail after this.

<Arguments>

None

<Exceptions>

None

<Side Effects>

Pending local recv and send calls will have an exception.

<Resource Consumption>

If the connection is already closed, no resources are consumed. This operation consumes 64*2 bytes of netsend (FIN/ACK, Last-ACK) and 64 bytes of netrecv (FIN/ACK). If applicable, this call stops consuming the corresponding outsocket.

<Returns>

True if this is the first close call to this socket, False otherwise.


socket.recv(numbytes)


Receives data that was sent by the connected party using send. Note that this may return less than numbytes worth of data. Also, note that if the other party does s.send('hello'); s.send('Guten Tag'), the other party who calls recv may get 'helloGuten Tag', 'h', or any other subset of the total data.

  • Doc string:

<Purpose>

Receives data from a socket. It may receive fewer bytes than requested.

<Arguments>

numbytes:

The maximum number of bytes to read.

<Exceptions>

SocketClosedLocal? (descends NetworkError?) if the socket is closed locally.

SocketClosedRemote? (descends NetworkError?) if the socket was closed remotely and there is no more data to be read.

XXXException if the connection is broken due to a network problem. Conrad: is this substantially different from the socket being closed remotely?

LocalIPChanged (descends NetworkError?) if the local system connection is broken because the local system changes its IP address.

<Side Effects>

If there is no buffered data, this call will block the thread until the other side calls send.

<Resource Consumption>

This operation consumes 64 + size of returned data in bytes of netrecv and 64 bytes of netsend (ACK).

<Returns>

The data received from the socket (as a string).


socket.send(message)


Sends data to the connected party. Note that this may send less than the entire message. If the connection is disconnected, there is no guarantee that the other party was able to recv the data. If the other party doesn't call recv, send may block indefinitely. If the other party closes the connection, send will raise an exception.

  • Doc string:

<Purpose>

Sends data on a socket. It may send fewer bytes than requested.

<Arguments>

message:

The string to send.

<Exceptions>

SocketClosedLocal? (descends NetworkError?) if the socket is closed locally.

SocketClosedRemote? (descends NetworkError?) if the socket was closed remotely.

XXXException if the connection is broken due to a network problem. Conrad: see my comment above

LocalIPChanged if the local system connection is broken because the local system changes its IP address.

<Side Effects>

This call may block the thread until the other side calls recv.

<Resource Consumption>

This operation consumes 64 + size of sent data in bytes of netsend and 64 bytes of netrecv (ACK).

<Returns>

The number of bytes sent. Be sure not to assume this is always the complete amount'''


socket.willblock()


(added call)

Returns a tuple of booleans (recvwillblock,sendwillblock) indicating if a socket may block if send or recv are called. This allows the caller to determine if a deadlock may occur if the call is performed. Note that returning True doesn't necessarily mean the call will block. It could be that data was recently consumed / sent so the call will now proceed without blocking.

  • Doc string:

<Purpose>

Determines if a socket may block if send or recv are called.

<Arguments>

None.

<Exceptions>

SocketClosedLocal? if the socket is closed locally.

SocketClosedRemote? if the socket was closed remotely and there is no data pending for recv.

<Side Effects>

None.

<Resource Consumption>

None.

<Returns>

A tuple (recvwillblock, sendwillblock) of booleans.


tcpserversocket.getconnection()


Receives a connection that was initiated to an IP and port. waitforconn can be built in a user level library on top of this.

  • Doc string:

<Purpose>

Obtains an incoming connection to an IP and port.

<Arguments>

None

<Exceptions>

LocalIPChanged if the local IP address has changed and the tcpserversocket is invalid

PortRestrictedException? (descends ResourceException?) if the port number is no longer allowed.

SocketClosedLocal? if tcpserversocket.close() was called.

<Side Effects>

None

<Resource Consumption>

Upon success, this operation consumes 64*2 bytes of netrecv (SYN, ACK), 64 bytes of netsend (SYN/ACK) and an outsocket.

<Returns>

A tuple consisting of the remote IP, remote port, and a socket object.


tcpserversocket.close()


Closes the socket. Any further local calls to getconnection will result in an exception.

  • Doc string:

<Purpose>

Closes a socket that is listening for connections. Pending connections will be closed / refused.

<Arguments>

None

<Exceptions>

None

<Side Effects>

The IP and port can be reused by other tcpserversockets after this.

<Resource Consumption>

If applicable, this operation stops consuming the corresponding insocket.

<Returns>

True if this is the first close call to this socket, False otherwise.


udpserversocket.getmessage()


Receives a message that was sent to an IP and port. recvmess can be built in a user level library on top of this.

  • Doc string:

<Purpose>

Obtains an incoming message that was sent to an IP and port.

<Arguments>

None

<Exceptions>

LocalIPChanged if the local IP address has changed and the udpserversocket is invalid

PortRestrictedException? if the port number is no longer allowed.

SocketClosedLocal? if udpserversocket.close() was called.

<Side Effects>

None

<Resource Consumption>

This operation consumes 64 + size of message bytes of netrecv

<Returns>

A tuple consisting of the remote IP, remote port, and message.


udpserversocket.close()


Closes the udp server socket. Any further local calls to getmessage will result in an exception.

  • Doc string:

<Purpose>

Closes a socket that is listening for messages.

<Arguments>

None

<Exceptions>

None

<Side Effects>

The IP address and port can be reused by other udpserversockets after this.

<Resource Consumption>

If applicable, this operation stops consuming the corresponding insocket.

<Returns>

True if this is the first close call to this socket, False otherwise.


circularlog(string)


(added call -- replaces print)

Writes a string to the circular logging buffer. A library will be added that constructs a function that log(*args) on top of this.

There is a debate over whether or not we need this call

  • Doc string:

<Purpose>

Writes data to the circular logging buffer.

<Arguments>

The string to write out.

<Exceptions>

TypeError? if the string argument isn't a string.

<Side Effects>

The data is written to the circular logging buffer.

<Resource Consumption>

This operation consumes lograte of the size of the string. This assumes that the string is less than the log size. If the string is larger, then it consumes at most the log size.

<Returns>

None.


getthreadname()


(added call)

Returns a unique name that indicates the thread's name. Don't use this to derive any meaning other than string uniqueness.

  • Doc string:

<Purpose>

Returns a string identifier for the currently executing thread. This identifier is unique to this thread.

<Arguments>

None.

<Exceptions>

None.

<Side Effects>

None.

<Resource Consumption>

None.

<Returns>

A string identifier.


createvirtualnamespace(code, name)


(added call)

Wraps any arbitrary code after performing a safety evaluation. Provides a method to evaluate the code.

  • Doc string:

<Purpose>

Returns a virtualnamespace object which supports evaluation of the code in an arbitrary global context.

<Arguments>

code: The string code to check for safety and store for future evaluation.

name: The name for this module. Used during initialization only, and so a stack trace can show the name of the module instead of just <string>.

<Exceptions>

A CodeUnsafeError? will be raised if the static code analysis fails. This can be due to unsafe constructs, invalid syntax, or an evaluation timeout.

<Side Effects>

Other calls to createvirtualnamespace() will block since safety checks are performed serially.

Another process will be launched to check the code for safety. This has memory and CPU ramifications, since we will not account for it's resource consumption. The memory use will likely exceed what is allowed per vessel, since the memory used seems to grow faster-than-linarly with respect to LOC.

It usually takes 0.2-0.3 seconds to launch a process, pipe the code, evaluate for safety, and return.

<Resource Consumption>

None

<Returns>

A virtualnamespace object


virtualnamespace.evaluate(context)


(added call)

Evaluates the code wrapped by the virtualnamespace in a given context.

  • Doc string:

<Purpose>

Evaluates the code in a given context.

<Arguments>

context: A dictionary or SafeDict dictionary to execute the code in. If a dictionary object is provided, an attempt is made to convert it to a SafeDict object before evaluating the code.

<Exceptions>

If the context cannot be converted to a SafeDict due to safety issues, an XXXException will be raised. Any exception that the code raises during evaluation will not be caught. Conrad: do we care what exception this is? Should user code expect to catch/handle this?

<Side Effects>

The provided context will likely be modified during execution.

<Resource Consumption>

Whatever is consumed by the executed code

<Returns>

The context that was used during evaluation. If the context was a SafeDict originally, this is the same object. If the provided context was a dict, this is the converted SafeDict version.


getresources()


(added call)

Determines the resource usage limits and current usage.

  • Doc string:

<Purpose>

Returns the resource usage limits and the current usage.

<Arguments>

None.

<Exceptions>

None.

<Side Effects>

Calls to this function will be serialized.

<Resource Consumption>

None (???)

<Returns>

A tuple of dictionaries (limits, usage). Limits is a dictionary which contains the maximum utilization of a resource. It contains all of the resources as defined in the restrictions file. The user can also determine the allowed conn and mess ports by checking for their respective entries.

The usage dictionary contains the current usage of all the resources. It has all the same entries as the limits dictionary, but has an additional "threadcpu" key, which is the amount of CPU time in seconds the current thread has executed for.