NAME
src/pmc/socket.pmc - Socket PMC
DESCRIPTION
The Socket PMC performs abstract network I/O operations.
Vtable Functions
void init()
Initializes a newly created Socket object.
PMC *clone()
Create a copy of the socket handle.
void mark()
Mark active socket handle data as live.
void destroy()
Free structures.
INTVAL get_bool()
Returns whether the Socket is currently open.
Methods
socket(INTVAL fam, INTVAL type, INTVAL proto)poll(INTVAL which, INTVAL sec, INTVAL usec)
Watches the socket for sockaddr(STRING * address, INTVAL port, INTVAL family :optional)getaddrinfo(STRING * address, INTVAL port, INTVAL protocol, INTVAL family, INTVAL passive)remote_address()local_address()METHOD is_closed()
Test if the socket is closed.
getprotobyname(STRING * name)connect(PMC * address)
Connects a socket object to an address.The asynchronous version takes an additional final PMC callback argument,
and only returns a status object.
When the socket operation is complete,
it invokes the callback,
passing it a status object and the socket object it was called on.
[If you want notification when a connect operation is completed,
you probably want to do something with that connected socket object.]
recv()
Receives a message from a connected socket object.
It returns the message in a string.The asynchronous version takes an additional final PMC callback argument,
and only returns a status object.
When the recv operation is complete,
it invokes the callback,
passing it a status object and a string containing the received message.If the socket is closed or on other errors,
it throws an .EXCEPTION_PIO_ERROR Exception.
send(STRING *buf)
Sends a message string to a connected socket object.The asynchronous version takes an additional final PMC callback argument,
and only returns a status object.
When the send operation is complete,
it invokes the callback,
passing it a status object.
bind(PMC *host)listen(INTVAL backlog)accept()METHOD read(INTVAL bytes)
Read up to the given number of bytes from the socket and return them in a string.This method behaves always the same as recv().
Only if the socket is already closed return an empty string.
METHOD readline(STRING delimiter)
Read a line from the socket and return it in a string.
If METHOD puts(STRING *buf)
Print the string to the socket.
sec seconds and usec microseconds.
which is a bitmask representing the states you want to watch for.
Or together 1 for readable,
two for writeable,
and four for exceptions.
sockaddr returns an object representing a socket address,
generated from a port number (integer) ,
address (string) and an optional address family (integer).
If no address family is given,
it defaults to IPv4.
getaddrinfo returns an array of Sockaddr PMCs representing the result of the getaddrinfo(3) function which consists of multiple socket addresses,
including family and protocol.
It can be passed to bind() or connect().
remote_address returns the remote address of this socket PMC.
local_address returns the local address of this socket PMC.
getprotobyname returns a protocol number suitable for passing to socket,
based on the given protocol name.
This is normal only necessary when opening sockets in raw mode.
bind binds a socket object to the port and address specified by an address object (the result of getaddrinfo).The asynchronous version takes an additional final PMC callback argument,
and only returns a status object.
When the bind operation is complete,
it invokes the callback,
passing it a status object and the socket object it was called on.
[If you want notification when a bind operation is completed,
you probably want to do something with that bound socket object.]
listen specifies that a socket object is willing to accept incoming connections.
The integer argument gives the maximum size of the queue for pending connections.There is no asynchronous version.
listen marks a set of attributes on the socket object.
accept accepts a new connection on a given socket object,
and returns a newly created socket object for the connection.The asynchronous version takes an additional final PMC callback argument,
and only returns a status object.
When the accept operation receives a new connection,
it invokes the callback,
passing it a status object and a newly created socket object for the connection.
[While the synchronous accept has to be called repeatedly in a loop (once for each connection received),
the asynchronous version is only called once,
but continues to send new connection events until the socket is closed.]
delimiter is present,
it is used to determine line endings instead of the default \n.