Package org.gnome.gio

Interface PollableOutputStream

All Superinterfaces:

Proxy

All Known Implementing Classes:

ConverterOutputStream, MemoryOutputStream, PollableOutputStream.PollableOutputStream$Impl

@Generated("io.github.jwharm.JavaGI")
public interface PollableOutputStream
extends Proxy

GPollableOutputStream is implemented by OutputStreams that can be polled for readiness to write. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.

Some classes may implement GPollableOutputStream but have only certain instances of that class be pollable. If canPoll() returns false, then the behavior of other GPollableOutputStream methods is undefined.

Since:

2.28

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	PollableOutputStream.PollableOutputStream$Impl	The PollableOutputStream$Impl type represents a native instance of the PollableOutputStream interface.
static class	PollableOutputStream.PollableOutputStreamInterface	The interface for pollable output streams.

Method Summary

Modifier and Type	Method	Description
default boolean	canPoll()	Checks if this PollableOutputStream is actually pollable.
default Source	createSource(@Nullable Cancellable cancellable)	Creates a GSource that triggers when this PollableOutputStream can be written, or cancellable is triggered or an error occurs.
static @Nullable Type	getType()	Get the GType of the PollableOutputStream class
default boolean	isWritable()	Checks if this PollableOutputStream can be written.
default long	writeNonblocking(@org.jspecify.annotations.Nullable byte @Nullable [] buffer, @Nullable Cancellable cancellable)	Attempts to write up to count bytes from buffer to stream, as with g_output_stream_write().
default PollableReturn	writevNonblocking(@Nullable OutputVector @Nullable [] vectors, @Nullable Out<Long> bytesWritten, @Nullable Cancellable cancellable)	Attempts to write the bytes contained in the nVectors vectors to stream, as with g_output_stream_writev().

Methods inherited from interface org.javagi.base.Proxy

handle

Method Details

getType

static @Nullable Type getType()

Get the GType of the PollableOutputStream class

Returns:

the GType

canPoll

default boolean canPoll()

Checks if this PollableOutputStream is actually pollable. Some classes may implement GPollableOutputStream but have only certain instances of that class be pollable. If this method returns false, then the behavior of other GPollableOutputStream methods is undefined.

For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa.

Returns:

true if this PollableOutputStream is pollable, false if not.

Since:

2.28

createSource

default Source createSource(@Nullable Cancellable cancellable)

Creates a GSource that triggers when this PollableOutputStream can be written, or cancellable is triggered or an error occurs. The callback on the source is of the GPollableSourceFunc type.

As with g_pollable_output_stream_is_writable(), it is possible that the stream may not actually be writable even after the source triggers, so you should use g_pollable_output_stream_write_nonblocking() rather than g_output_stream_write() from the callback.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns false for stream.

Parameters:

cancellable - a GCancellable, or null

Returns:

a new GSource

Since:

2.28

isWritable

default boolean isWritable()

Checks if this PollableOutputStream can be written.

Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_output_stream_write() after this returns true would still block. To guarantee non-blocking behavior, you should always use g_pollable_output_stream_write_nonblocking(), which will return a IOErrorEnum.WOULD_BLOCK error rather than blocking.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns false for stream.

Returns:

true if this PollableOutputStream is writable, false if not. If an error has occurred on stream, this will result in g_pollable_output_stream_is_writable() returning true, and the next attempt to write will return the error.

Since:

2.28

writeNonblocking

default long writeNonblocking(@org.jspecify.annotations.Nullable byte @Nullable [] buffer,
 @Nullable Cancellable cancellable)
                       throws GErrorException

Attempts to write up to count bytes from buffer to stream, as with g_output_stream_write(). If this PollableOutputStream is not currently writable, this will immediately return IOErrorEnum.WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a GSource that will be triggered when this PollableOutputStream is writable.

Note that since this method never blocks, you cannot actually use cancellable to cancel it. However, it will return an error if cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled.

Also note that if IOErrorEnum.WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same buffer and count in the next write call.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns false for stream.

Parameters:

buffer - a buffer to write data from

cancellable - a GCancellable, or null

Returns:

the number of bytes written, or -1 on error (including IOErrorEnum.WOULD_BLOCK).

Throws:

GErrorException - see GError

writevNonblocking

default PollableReturn writevNonblocking(@Nullable OutputVector @Nullable [] vectors,
 @Nullable Out<Long> bytesWritten,
 @Nullable Cancellable cancellable)
                                  throws GErrorException

Attempts to write the bytes contained in the nVectors vectors to stream, as with g_output_stream_writev(). If this PollableOutputStream is not currently writable, this will immediately return %GPOLLABLERETURNWOULDBLOCK, and you can use g_pollable_output_stream_create_source() to create a GSource that will be triggered when this PollableOutputStream is writable. error will not be set in that case.

Note that since this method never blocks, you cannot actually use cancellable to cancel it. However, it will return an error if cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled.

Also note that if PollableReturn.WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same vectors and nVectors in the next write call.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns false for stream.

Parameters:

vectors - the buffer containing the GOutputVectors to write.

bytesWritten - location to store the number of bytes that were written to the stream

cancellable - a GCancellable, or null

Returns:

%GPOLLABLERETURNOK on success, PollableReturn.WOULD_BLOCK if the stream is not currently writable (and error is not set), or PollableReturn.FAILED if there was an error in which case error will be set.

Throws:

GErrorException - see GError

Since:

2.60