class AsyncOutputBuffer
Defined at line 65 of file ../../src/developer/debug/zxdb/console/async_output_buffer.h
This class is for collecting formatted output that might be produced in an asynchronous manner
across many components.
Formatted text (in the form of an OutputBuffer) can be appended or more AsyncOutputBuffers can be
appended, building up a tree of output. The various parts of this tree can be filled in
asynchronously and the toplevel buffer's callback will be issued when everything is marked
complete.
Usage guidelines for general sanity:
- The same code is responsible for Complete()ing an AsyncOutputBuffer as for creating it.
- Don't pass an AsyncOutputBuffer to another function and have the function Complete() it.
- Functions that need async output should generally return an AsyncOutputBuffer that the
function arranges to be Complete() when possible. Callers can append this to other buffers as
needed.
- If a function needs to append to an existing AsyncOutputBuffer, pass by raw pointer and do
not have the function Complete() it. If that function needs to append asynchronously do
something, it should append a new AsyncOutputBuffer that it will take responsibility for
Complete()ing.
Memory management: This is a tree structure. The ownership of the tree starts at the root (the
original AsyncOutputBuffer the caller creates). This in turn owns all child pending
AsyncOutputBuffers. Each buffer installs a callback on its children to know when the children are
marked complete. These must be non-owning pointers to avoid reference cycles.
Example:
// Creates a buffer and appends some text to it.
auto out = fxl::MakeRefCounted
<AsyncOutputBuffer
>();
out->Append("Hello");
// Now have somebody asynchronously append to this placeholder in the
// middle. This might happen after the next call that append "Goodbye".
auto sub = fxl::MakeRefCounted
<AsyncOutputBuffer
>();
// Could also Append(sub) here, the order won't matter.
DoSomethingWithACallback(
[sub](std::string value) {
sub->Append();
sub->Complete();
});
out->Append(sub);
out->Append("Goodbye");
out->Complete();
Public Methods
void SetCompletionCallback (CompletionCallback cb)Setting the completion callback will assert if the buffer is_complete() because in that case it
will never be called.
This can only be set to a nonempty function once, but it can be set with an empty function to
clear it.
The caller must ensure that it stays alive longer than this AsyncOutputBuffer if there are
any back-pointers (as there normally are) from the callback. In practice this means that
AsyncOutputBuffers that have non-complete children (which implies waiting callbacks) must keep
owning references to those children also. Any external setters of this callback (like the
Console) must also keep such owning references if they have installed a callback.
Defined at line 13 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Append (std::string str, TextForegroundColor fg, TextBackgroundColor bg)Mirrors the OutputBuffer API with the addition of being able to append AsyncOutputBuffers.
Defined at line 21 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Append (fxl::RefPtr<AsyncOutputBuffer> buf)Defined at line 26 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Append (Syntax syntax, std::string str)Defined at line 44 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Append (OutputBuffer buf)Defined at line 49 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Append (const Err & err)Defined at line 55 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Complete ()Call to mark this output buffer complete. This will issue the callback if there is one
registered. See is_complete() for additional discussion.
Doing additional appends or making it complete again after this call will trigger a debug
assertion.
Defined at line 60 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Complete (std::string str, TextForegroundColor fg, TextBackgroundColor bg)Helper functions that do Append(...) + Complete() since this is a very common use case.
Defined at line 66 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Complete (fxl::RefPtr<AsyncOutputBuffer> buf)Defined at line 71 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Complete (Syntax syntax, std::string str)Defined at line 76 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
void Complete (OutputBuffer buf)Defined at line 81 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
bool is_complete ()Returns true if the buffer has been marked complete (there will be no more nodes appended to
it) and all of the children are also is_complete(). Marking a buffer complete and it having
complete children are independent events.
Defined at line 85 of file ../../src/developer/debug/zxdb/console/async_output_buffer.h
void Complete (const Err & err)Defined at line 86 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
OutputBuffer DestructiveFlatten ()Once this buffer is_complete(), the spans and any sub-AsyncOutputBuffers can be flattened into
one vector.
This operation is destructive so can only be called once. This node and all child nodes will be
empty after this call.
Defined at line 91 of file ../../src/developer/debug/zxdb/console/async_output_buffer.cc
Friends
class MakeRefCountedHelperclass RefCountedThreadSafe